Naming Conventions

Hey dd, I too used Alexander's params to local vars function. You can see it here.

However, when you look at many other programming languages, the use of brackets is never used for function declarations. I don't know exactly why he chose them, but I opted to switch to parens because it's more common and something you're used to when reading code quickly. Having to 'interpret' the [ ] even though you know it's used for parameters slows you down. Plus, FileMaker already has the use of [ ] for repetitions ( e.g FunctionalArea » Tablename::repeatingFieldName[2] )

With regards to specifying optional parameters, this is something we can debate if it should be used. Recently, I started using a simplified variation of script parameters. I only specify the absolute required inbound parameters for the script to function. However, I do allow additional parameters to be passed in. For these parameters, I am documenting their availability within the script header such as this.

Script name Handle Error ( errorNum, scriptName )

#
# ==============================================
# Purpose:              Error handler
# Parameters:          
#                       ---------------------------
#                       $errorNum = (num) error number FMP or override
#                       $scriptName = (string) name of script which had error
#                       $type = (enum) CL, FMP - where FMP = FileMaker, CL = CustomList
#                       $data = (string) any inbound error text, like from CustomList function
#                       ---------------------------
# Called From:          (script) any
# Author:               Matt Petrowsky
# Notes:                none
# ==============================================
#

Note the additional optional parameters of $type and $data

Using a reserved local variable of $checkScriptName, the name of the script can optionally be used instead of absolutely used to enforce the existence of the required parameters. Taking this route didn't seem to limit the number of inbound parameters a script could accept.

One thing I kept in mind while documenting, was the fact that most all other programming languages take their parameters in an ordinal fashion. This too is a convention that is good to follow even though we can use name/value pairs. As well, other languages will take inbound parameters which are an array.

My switch from using dedicated custom functions for assigning parameters to using FileMaker's Quote function was prompted by trying to make code even more readable. Wherein, seeing this in a script call is easier to read - at least to me.

Perform Script [ "Handle Error ( error, script )"; Parameter:
          List (
            AppError;
            "$error=" & Quote ( -CustomListError ( $result ) ); // override fmp error with CL error
            "$type=" & Quote ( "CL" ); // set error type
            "$data=" & Quote ( $result )
          )
]

Seeing the dollar sign just sets the code apart and is very apparent as opposed to this. Where you have to determine if the key for the variable is a literal or not. I'm going for the quickest possible recognition of what things are.

Perform Script [ "Show Dialog [ method ; title; content ]"; Parameter:
          # ( "method" ; "filemaker" ) &
          # ( "title" ; "Successful send" ) &
          # ( "content" ; "Thank you for sending!¶Your contribution will be reviewed." )
]

I'm on the fence about dot notation for custom functions. FileMaker is NOT object oriented, and I don't want to confuse developers used to using object-oriented tools. However, it is helpful to group related custom functions by prefix. So I normally use and underscore delimiter instead of a dot: UUID_New, UUID_GetTimestamp( uuid ), and UUID_GetNICAddress( uuid ).

The reason I've flipped my waffle over is due to a few issues.

1. Because I realized that the larger mind share of custom functions created lean towards TitleCamelCase.
2. Because I realized I was confusing myself with some of my own functions. While I was standardized on "var." as the prefix for Let variables, using var.eval (my script parameter function) was confusing within code.*
   ^{see note below}
3. Because I wanted very distinct differences between the use of case, dot and underscore.
4. Because it just "felt right" when looking at calculation code to see familiar looking FunctionCalls.

One variation I could see is keeping, or suggesting as an alternative, a change in case. Such that, object.id() becomes Object.Id(). The issue of going with title case does somewhat remove the confusion within code between tab.name and Tab.current, where the later is now identified as a custom function because of case. However, going this route would then mean that it would be advised to not use the reserved object names for any custom function prefix.

I think I would rather give in to using the FileMaker familiar format of TabCurrent() and get more "buy in" by those adopting the standards.

* Yes, I could have renamed my custom function var.eval() to something else, but it showed me that using a dot within object names, custom functions, let variables and global variables was a bit too broad and didn't fit the current FileMaker function method. When I came to realize that distinguishing my custom functions from internal functions wasn't that big of a deal I decided this was the better way to go. Plus, it's quite easy to rename your custom functions

Which means you just need a wrapper function for calling via URL and a internal function for other users, surely?

Hey Matt, I believe you are doing the same in essence, it looks like your prefix of C__ is designed to force the sort order when choosing a TO while developing.

The proposed standard above does the same thing. The FunctionalName is supposed to be well-structured and used to collect all TOs within that functional aspect of the solution. Yes, it requires more work (because you have to think about it before you name it), but it essentially forces a degree of automatic documentation. Plus, for many tables "away" you can follow the naming prefix. In my example I showed in the video on the magazine site I used the following.

SideBar » Library
SideBarType » Sources
SideBarMissing » Sources

Where the prefix of SideBar (of which I only had one in my solution) identifies the function use of those TOs. I can see that the first is tied to the Library table and the other two are tied to the Sources table. Extending the FunctionalName by using Type and Missing give me a clue about what they do or can be used for (e.g. Type of Sources and Missing Sources).

While you do lack any identification of the absolute field used for the relationship, I've noticed that once I've stopped working on a particular aspect of a solution I end up having to make that obligitory trip back into the graph months later just to see what the keys and chain of relationships are anyway. For this reason I opted for clarity. The other two goals were to not introduce spaces or the underscore and use the » character to identify the table portion of a field reference.

One suggestion first, if this is not something you have tried and you're commenting based on first impressions, can you hack up a small little solution and try out the suggestion? Maybe make a fake Teacher/Student/Classes database using this approach?

This is certainly possible. Let's wait and get a few more people actively involved to see if this is warranted.

For right now, it's easiest to read on one page.

As a participant, make sure and read up on the wiki notation guide

I second the motion.

Please break these elements down into different sections. This will make it easier to browse comments to the related elements.

Arnold Kegebein

arnold (at) kegebein (dot) net

Each major section has now been made into a subsection under this section. Comments should be made on each section. I don't know that I can move comments - I'll have to look into it.

When referring to a Table::field in a calculation, we aren't always referring to data in one record. For "Sum ( Related » Invoices::amount )", the plural form is more semantically consistent. Plural form may also be one more signal distinguishing between tables and other objects. That said, the singular reference to one field in one record is definitely the more common in my experience. A stronger argument for singular table names might be that the names for foreign key fields can be more semantically accurate. "id_invoices" doesn't make much sense if it only refers to one invoice. (It may make sense for a multi-line foreign key; but that's much less common, and therefore less of a priority.)

I've used the underscore prefix for key fields too, with two underscores for the primary key and one underscore for foreign keys so the primary key always sorts above the foreign keys. The only problem I've encountered with that is that some other technologies that we might like to pull data from FileMaker don't like underscores at the beginning of field names. In SQL, you'd have to put __id in quotes to use it. I think it's a small and worthwhile price to pay, but I'm only one guy. SQL developers may have a different opinion.

I agree, UUID is field content and should be placed in a different section of this wiki.

But regarding the type of UUID, I do not think, this should be mandatory part of a coding standard. Recommendation perhaps, or included as additional information for interested developers, but do not make it a required standard.

Arnold Kegebein
arnold (at) kegebein (dot) net

Good point. I agree, let's revise it.

File naming? Yes, I agree. There should definitely be standard for that.

My own ref. is here:

http://www.fimano.dk/filemaker/udviklerkonventioner.html#01

In case any of you have trouble reading Danish, I will translate below :-)

- Not mentioned in original FDC, but still relevant.

- Versioning is sometimes needed. This should be on [enclosing] folder level, not to the solution file(s).

- Never change a file's name, see below.

- 1 and only 1 period in the name: FileName.fp7

- No spaces, no special chars.

- Prefix with shortname of customer / solution, like FMstd_CMS.fp7, FMstd_CMS_data.fp7

- A bug in FMP (that may or may not be fixed by now) would keep names that the file has had previously in its lifetime.