It's extremely advantageous to provide as much documentation within your code as is necessary. Code itself should be somewhat self-documenting through the use of readable structures. But, to supplement the code, commenting is used in order to clearly explain the intent of the code.
C style block comments (/* */) and standard inline C++ comments (//) are both available within Claris/FileMaker, though the former is discouraged when used within the middle of functions (even when a function spans multiple lines). Block comments are best used either before or after segments of code.
When possible, use inline comments (those preceded by the double slashes) on a dedicated line. Trailing comments should be used sparingly and limited to very few words.
/* Creates the display portion of a customer's active state. It minimally requires the first name field (not empty validated) and shows their active state. */ Let ( [ // Determine if all required values are populated ~validName = not ( IsEmpty ( Table::nameFirst ) and IsEmpty ( Table::nameLast ) ); // Combine name values ~fullName = Table::nameFirst & If ( not IsEmpty ( Table::nameLast ) ; " " & Table::nameLast ); // Compose display text ~prefixText = "is an %state% customer"; ~activeText = If ( Table::active ; "active" ; "inactive" ); // active is boolean ~displayText = Substitute ( ~prefixText ; "%state%" ; ~activeText ) ]; If ( not ~validName ; "Missing information" ; List ( ~fullName ; ~displayText ) ) )
Increased comment readability
Can be achieved by adding a line after inline comments. This is preferential based on whether you like more compact code or the more readable description.
Use one or more spaces before any text added to a script comment step. This increases the readability of the step by creating a white space margin while reviewing scripts.
# One or more spaces at the start of any script comment step increases readability.
#Not using spaces in front of comments makes them harder to read
Also note that not using a period at the end of the second comment just feels "off". Try to use normal sentence structures for your comments.
Reading what a script does, what it affects, and how the script has changed is critical to understanding where it fits into the solution. The following guidelines can be used for commenting your scripts. This is only an example and there are various formats to choose from. The key is to pick a format and stay consistent.
# # =================================================================== # Purpose: Describe the purpose of the script [short version] # Parameters: one ; two ; three # --------------------------- # $one = (enum) load, unload # $two = (string) second parameter # $three = (num) expected # --------------------------- # Called From: (script) any # Author: Matt Petrowsky # Notes: Additional information [long version] # Revsion: Last change: 2010/10/23 by MP :: A single comment step with multiple lines # =================================================================== #
For complex scripts, the revision area within the comment steps is something which contains the latest change date and authorship of the revision. A unique line for each change should be used. Within the comment steps it might look like the following.
# Revision: Last change 2010/10/23 by MP # 2010/10/10 - MP - each line of history is within this one comment step # 2010/10/02 - MP - added the history field to the comments
Use some type of text expansion software to expand the current date into your comments. The suggested format is YYYY/MM/DD.
Not every script
Needs to be fully documented. Shorter, self explanatory scripts can often get by with just a few comment steps describing what their purpose is.
Complex custom functions should use, at minimum, the following header (or similar variation). Because the header of a custom function is multiple lines of text within the calculation dialog box, you can use spaces for indenting, instead of the proposed tabs. This makes the calculation header easier to read. Tip: many editors have a convert spaces to tabs and inverse functionality.
/** * ================================================================== * CustomFunction ( parameter1 ; parameter2 ) * * PARAMETERS: * @parameter1 (text) Input string * @parameter2 (num) Numerical value * RETURNS: * (bool) True or False based on proper * evaluation * DEPENDENCIES: * none * PURPOSE: * Use this function in order to accomplish * most wonderful things possible! * NOTES: * none * REVISIONS: * 2010/10/23 - Initial release * 2010/10/27 - Modified to fix issue * 2010/10/31 - Not returning Boolean result * ================================================================== * */
Wrapping lines within the header comment
Using an external text editor (not the calculation dialog box in Claris/FileMaker) will make it easier to wrap individual lines to a fixed length. Many editors exist which have this functionality.
There are various formats to emulate when commenting within your solution. Here are just a few on the Internet. You can borrow from these sources or other solutions.