Copying & Pasting these conventions

Copies of these standards can be found within the Standards.fp7 file on this wiki.

Calculation commenting

  • C style comments (/* */) and standard C++ comments (//) are both fine, though the former is discouraged within functions (even for multiple lines, repeat the // single-line comment).

Single comment steps within scripts

Use one or more spaces before any text is added to a script comment step. This increases the readability of the step by creating a white space margin while reviewing scripts.

#  Use one or more spaces at the start of any script comment step to increase readability

good 

#Not using spaces in front of comments makes them harder to read

bad

Script commenting

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.

#
# ===================================================================
# 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: 10/10/10 by MP :: A single comment step with multiple lines
# ===================================================================
#

The Revision field within the comment is one single script step which contains the latest change date and a date or date/timestamp line for each change documented. Within the comment step it looks like the following.

 Revision:

Last change: 10/10/10 by MP
::
10/9/10 - MP - each line of history is within this one comment step
10/10/10 - MP - added the history field to the comments

The utility of the history field is being able to use the return key to open the comment dialog for review and close the dialog easily using the escape key.

Shortcuts for inserting date/time values

Using a string expansion program for inserting dates and times into your comments is very helpful. For example, typing dts can be expanded to the current Date time short equivalent. Find a list of these tools in Keyword expansion tools in Developer Tools

Custom function commenting

Custom functions should use, at minimum, the following header. 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:
 *            10/23/10 - Initial release
 *            10/27/10 - Modified to fix issue
 *            10/31/10 - No returning Boolean result
 * ==================================================================
 *
 */

Wrapping lines within the header comment

Using an external editor will make it easier to wrap individual lines to a fixed length.

Commenting conventions to borrow from

The above standards are adapted from the following sources

Wikipedia Doxygen Article
Doxygen Web Site

  • No labels

23 Comments

  1. Matt Navarre

    Every script, and every custom function should contain comments outlining the function.

    1. Matt Petrowsky

      Very much agreed. This area needs work in terms of what specifically should be commented within each area. For example, my scripts are commented as such.

      #
# ==============================================
# 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
# ==============================================
#

      Agreeing on the labels and format is something open for discussion.

      1. Anonymous

        Matt - I very much agree with the labels and formatting for the above example.

        What I'd love to add is add the following section - either after "Notes:" or in an optional section immediately below the block with it's own "===..." trailing line:

        #...
# Author:           Matt Petrowsky
# Notes:            none
# ==============================================
# Changelog:
		08/20/2010 - Jane Developer - Updated check for minimum required version to FMP 11.
		10/03/2010 - Joe Developer - Changed some function to account for a new business condition.
# ==============================================
#...

        This is incredibly useful for multiuser development environments where things change faster than any one human can keep up with in large solutions...

        Thanks,

        --Perren

        1. Anonymous

          Grr...the formatting didn't come through. I hope everyone reading get's the basic idea...oops.

          --Perren

  2. Jeremy Bante

    Are spaces at the beginning of a script comment too small a nit to pick, or is it just me?

  3. Jeremy Bante

    Could we capitalize section labels in script header comments to be consistent with the custom function comments?

    1. Matt Petrowsky

      Personally, the amount of effort to hit the spacebar two or more times before typing, for the sake of clean looking code, is worth it.

      Of course, if the spaces aren't there I'm sure the words will still make sense (wink)

      When you compare the two side-by-side, the clarity is pretty obvious - at least to me.

      I'm ambivalent with the headers being CAPS vs. Title. Are we cool with making that one unspecified? I'd like to use Title case myself.

      1. Jeremy Bante

        I don't doubt that it's worth the effort to type two spaces at the beginning of a comment, only that's it's worth it to call comments without two spaces incorrect. I guess I'm testing out a threshold of authority of the standard: If I see something that doesn't fit the Standards in a script (or any other piece of programming in a file) someone else wrote that's supposed to fit the Standards, do I feel the need to fix it? I wouldn't feel the need to fix a comment missing two spaces from the beginning. I probably wouldn't feel the need to change the capitalization on labels either, as long as different sections of a header comment are visually distinguished some way.

        1. Matt Petrowsky

          Totally get where you're coming from. Myself? Being as anal as I am, I would take the time to clean up a script that didn't have it - even if I didn't write it.

          If the standards establish the precedence, and a new developer reading this just does it from the start, then we have a much cleaner solution.

          I don't think we should view these things in terms of strict compliance - more like ideal guidelines. With most standards you always find enhancements and omissions by the wide range of developers who adopt them.

          It's not like we (currently the three of us) are going to start the "FileMaker Compliance Police". LOL - although it sounds fun. (wink)

          1. Perren Smith

            FileMaker Compliance Police sounds fun, but others who have a voice (<cough, cough...such as> Mr. Navarre <or anyone reading this>) are being awfully quiet on such minutiae...where is the public when we could use a voice of reason, or debate? ;)

            Or does it not really matter for a "standard"? Lately these days it's becoming increasingly important for me to be highly effective in my professional role...

            1. Matt Petrowsky

              Navarre is not on the google group. And even though he has an account on the wiki, I don't think he knows how to turn on space watching to be emailed.

              He probably has his own standards for doing things and it's going to be the people who adopt, contribute and use what we've started here who will get the most benefit.

              Just today I started a complete overhaul of one of my other solutions (based on these standards) and I'm REALLY liking where we're headed here. I'm grateful to all who have contributed to this. I hope we get a lot out of it!

          2. Jeremy Bante

            Would the Compliance Police get to wear uniforms?

            In my past life as a copy editor, it was always worth it to sweat the small stuff. It was also easy to get carried away and miss deadline. I'm just wondering if the subjective "Would I bother to fix it?" test might be a useful way to distinguish between guidelines that should be Best Practices vs Standards. A consultant, an in-house developers, and a shrink-wrap developer will each approach that question from a wildly different perspective, both in terms of where the code they're working with usually comes from, and what they're getting paid for. Are the differences too much for "Would I bother to fix it?" to be a useful meta-guideline?

            1. Perren Smith

              As the "in-house" guy if I'm anywhere near the "Retail rush" the answer is no as much as I personally hate to say it. Scope creep vs. real life business deadlines seems to be the biggest contention at hand....

    2. Perren Smith

      I'm on the fence about Title vs. CAPS on comment section labels...any references to other languages spec'ing one way or another to help persuade me?

      1. Arnold Kegebein

        I prefer the Title format. CAPS is 'yelling' to much.

  4. Arnold Kegebein

    Line breaks in comment

    Do you have any recommendations for the length of a comment line?

    For scripts, anything you write in a single comment step will be display in a single line in the script, no matter how many line breaks you add. I think, everything for one topic (e.g. Purpose) should be within a single command step. In the edit window, the comment text is automatically wrapped and therefore easily read. Do not create multiple command steps to break the purpose comment into readable line lengths.

    For custom functions, this might be different. Because the whole function code including the comments are within the same text field, manual line-breaks are recommended. My suggestion, use the minimum width of the custom function edit window as a guideline. A text line should not exceed this width (approx. 76 hyphens).

    Because of the limited space I'd rather use a small indent of the comment section.

    Instead of

    ...
 * Notes:
 *                 Try to always use the List() function when passing multiple values into
 *                 var.eval!
 *                 $checkScriptName is a reserved local variable used when you wish to
 *                 enforce that inbound parameters match the name of the script. It is
 *                 reset after the evaluation.
...

    I like to write

    ...
 * Notes:
 *   Try to always use the List() function when passing multiple values into var.eval!
 *   $checkScriptName is a reserved local variable used when you wish to enforce that
 *   inbound parameters match the name of the script. It is reset after the evaluation.
...

    1. Perren Smith

      For comment lines I stick to the equivalent of a default Terminal.app (Command Shell on windows) width. If a comment can't be done in 80 characters either shorten the wording or use multiple lines.

      But this is really an environmental issue with the developer at hand. Sometimes I'm working over VNC with small resolutions, but the other 98% of the time I'm on my MacBook Pro with 1680 x 1050 resolution. I can easily see 120 plus lines if a script window is fully maximized. 

      I lean towards the worst case for a developer in a client / hosted solution. Hopefully one would not need to quickly comprehend lines of script commenting remotely to fix an issue, but if so I appreciate easily readable documentation no matter the length of a line.

      It also prints easier if one wants to scribble on a script with a sharpie.

      1. Matt Petrowsky

        I agree with Perren on the environment issue. One thing I agree with is the max number of characters. I think it's the information that's most important and CAPS vs. Title can be up to the developer. I would treat this more like a suggestion. I prefer Title myself and I like having the left edge of the content to be non overlapping - but I'm flexible on this one.

        I'll revise based on these comments and also add in the Script headers - or a reference to them.

  5. Anonymous

    Just moved a whole solution over to the custom function style of header as found in the second example of the Standards fp7 file. The problem I always had with Matts style is that it is quite difficult to edit or create new lines as you have to count too many space presses and on Windows it doesn't seem to always line up properly.

    Takes more lines but just as readable and faster to implement

    1. Matt Petrowsky

      I agree that we'd need to go with something that is just as easy on Windows as it is on Mac.

      I like the readability when you use the spaces and I personal don't type new lines. I just use the editing command keys on a keyboard. Such as Command-LeftArrow to jump to the beginning of a line then holding down Command-Shift-RightArrow to select the whole line and then paste for reuse.

      I know there aren't as many command-based typers out there so we'll need to modify.

      How about this. Currently Jeremy us using a flush left style (which I'm not fond of because titles are blended with information, such as...

      /**
 * =====================================
 * #Assign ( parameters )
 *
 * PURPOSE:
 * #Assign ( parameters ) uses the output of the # ( name ; value ) function (or
 * the concatenated results from several #() calls) to declare and populate a
 * series of locally-scoped script variables.
...

      What if, like we're doing with code. We go with a one tab indent for lines after each section title within the header?

      /**
 * =====================================
 * #Assign ( parameters )
 *
 * PURPOSE:
 *      #Assign ( parameters ) uses the output of the # ( name ; value ) function (or
 *      the concatenated results from several #() calls) to declare and populate a
 *      series of locally-scoped script variables.
...

      This increases readability but doesn't add as much complexity as multiple spaces.

      1. Jeremy Bante

        I can live with that. It's also in-line with what Arnold was saying earlier.

  6. Anonymous

    Regarding the "Revision" section;

    1. I prefer to add new entries to the top of the list.  This offers these advantages:
      1. since the last change is shown first, the "Last change: 10/10/10 by MP" section is NOT needed (prevents having to enter the date in two places when you make a change)
      2. you are likely more interested in the latest changes, rather than the oldest, imagine if there were 50 entries and you always had to scroll to the bottom to see the newest info
    2. A universally understandable date format should be used. In Canada, 8/9/10 means Sept. 8 2010, in US it means Aug. 9 2010, In Japan it means Sep. 10 2008
      1. I prefer to use this format: YYYY-MMM-DD  (2010-AUG-09)
      2. Whatever format is decided on, it should use a 4 digit year to make it clear that it's the year.  I think using a 3 digit abbreviation of the Month is a good practice because it completely eliminates the possibility of the date being read any other way (when combined with a 4 digit year).

    - Dan Smith

  7. Anonymous

    I strongly second Dan's comment to put the latest comment to the top.  We have 4 developers and the occasional 'guest' If I am looking at a complex script that started in 2005 it can be hundreds of lines to the bottom.  us of a tool like text expander or typinator means with two characters d and s and a tab I get MM/DD/YYYY dhr to start the comment.

     

    doug rowe