Scripting Documentation Tips & Best Practices?

When I was adding some comments to a script, trying to document its perform-script dependencies, I realized script names could change, but the comments would not change automatically. It reminded me of philmodjunk's DIGFM presentation on How Brittle is Your Database?

Then I had an "aha!" moment. Why not just copy and paste all the Perform Script steps next to the comment and disable them like this?:

Then if the script name ever changes, the documentation automatically changes. It also easily provides some context, e.g. If the script dependency happens to be Perform Script or Perform Script on Server, or if there were parameters. The documentation will even reflect <unknown> if the script is is deleted, and documentation script references will show even in the Database Design Reports.

I'm guessing this technique might have been already obvious to others (or dismissed as problematic perhaps), which causes me to ask:

What other scripting documentation tips and best practices do other experienced developers have that we should all know?

It's important to tell future self and any team members what changed recently in a script. We have instituted a simple practice that looks like this.

As part of the "comment block" at the beginning:

#Modified: Developer Name, Date, describe what was changed.

Then at the spot where code changed:

#Dev Name, Date, Begin change

New code here

Old code, disabled, here

#Dev Name, Date, End change

This lets you quickly see what was changed, when and why. If you need to rapidly revert a change, you can quickly disable the new code and enable the old.

We use the dates to determine when to delete the comments and disabled script steps. Basically, team members are encouraged to remove those lines when the date indicates that the change was made a month or more in the past. This is to keep excessive comments/disabled code from rendering a script hard to read.

It's important to tell future self and any team members what changed recently in a script...

...

We use the dates to determine when to delete the comments and disabled script steps. Basically, team members are encouraged to remove those lines when the date indicates that the change was made a month or more in the past. This is to keep excessive comments/disabled code from rendering a script hard to read.

That's good advice. I try to keep some important history in script comments, as well, though more condensed than yours. If there's a related request ticket, I cite it. To avoid cluttering the top of the script, I put the history at the end in reverse order so I can keep it as long as I might ever want.

In general a similar practice occurs in the scientific community where a process or method is changed; that change is documented at the end of the SOP. It is part of any accreditation standard to retain the historical data. It even goes to the extreme that a spelling or grammar correction needs to be tracked.

I am surprise that FMP does not have a neat and native way to handle the tracking. many of the small specialized software we use have some type of mechanism that respects ISO.

Do you know if or why something like that hasn't been implemented? Would be nice to have a comment box associated with the script to hold that information to separate that information out and avoid "cluttering" of the actual scripts. Something like an extra window pane within the script workspace that can expand

...I am surprise that FMP does not have a neat and native way to handle the tracking....

Yes, in fact, it might be relatively straightforward for FileMaker Pro Advanced, to utilize the undo stack and keep it permanently attached to the script in some readable form, also tracking who made the change and when.

in our product, when you log in as admin, there's a button named "ChangeLog" on the main layout.

We use it to reach a table in which we write date, who, table, and a big description field in which you can write a lot of stuff. This helps us a lot when we want to know which changes we did after a certain date.

While there isn't yet a super-granular log in FileMaker like described above by badmonkey842 and eric, I do two things:

1. I keep extensive documentation at the top of the script, including a general change log.

B. If the changes are extensive to the script, I will start by duplicating the script and appending "DEPRECATED <my initials> <date>" to the duplicated script. I then put that script in a DEPRECATED folder for later reference. That way it can't be used accidentally and I can refer to what went before any time I want. I sometimes have several copies of different iterations of a script if it gets repeat visits.

I try to keep as much documentation internal to FileMaker as possible and keep external documentation limited to only that which is absolutely necessary--usually for communication with non developers. There nothing really wrong with setting up a bunch of design documents, but I find that it takes a lot of time to keep them up to date, complete and accurate.

Internal documentation that I've used in different places in addition to comment script steps:

Put layout text on your layout, either off to the right of the layout edge or with a Hide Object expression of True to document less than obvious layout features--such as a transparent slide control placed inside a popover.

Use the text boxes in the relationship graph to document relationships, especially if you've broken your graph up into modular groups

Use // To insert comments into all kinds of calculations to document important details such as:

build a "help system" used throughout the solution that pops up help information, with a special category of help articles that are only visible to full access developers. Use these to document layout and workflow design details as needed for your future reference and that of other developers in your team.

B. If the changes are extensive to the script, I will start by duplicating the script

I was about to write the same thing. I don't change script names beyond minor changes, e.g. adding a new parameter/return value to the end of a script name.

Major changes to a scripts functionality that requires a name change either involve a DDR and a major database update or all related uses, or duplicating the script to create a new script purpose for the job.

Each script is it's own "functional unit", and if the script change means that it performs a different function then it should be a new script.

E.g. FileMaker would not change the name of a script step if the functionality changed. They would create a new script step, and deprecate the old script step if necessary. One exception is the change that was done when "Show Message" changed to "Show Custom Dialog", but that was done over a breaking version, e.g. new file format where full re-testing was required...

Not sure if you understood my intention there. The duplicate is merely a snapshot of the script at that time for later reference. It is never to be used again. The original gets the modifications, so as not to break any references to it.

I understand now, that is a good way to keep old versions. If I do that I also put an "Exit Script" step at the top of the script so that any attempts to use the copy will fail since the deprecated script will likely be problematic if run.

Yes I do think that I am over-paranoid sometimes, but not others. I work on some databases that are also developed by the non-technical user and weird things happen so I try to minimise what they can do wrong.

My script documentation is generally limited to comments within the script itself. I add specific details at the top of the script- name, high level of what it's supposed to do, creation date, author, parameters, dependencies, and then a high level changelog.

Then in the body of the script, comments for each "section", with additional comments for anything that was gone a given way for a specific reason. These little breadcrumbs have tremendously helpful over the years, especially when you go back to update a script and wonder why you did something one way when there's an apparent better way. Sometimes there's a reason for it, while other times it could just be that you've learned a new technique.

Something that I have also started doing is to have a developer log within the solution. The sole purpose is to track changes, who requested the change, the reason for the change, the Time involved, any comments, and version control. It is also updated in the developer copy.

I find this very helpful when one has the moment of asking yourself just why you did something months later…!

Further to number 4, I have started listing the button actions in the *first* line of the Show Custom Dialog Message. That way, they're always visible in the script editor, available at-a-glance when writing the branching code that follows the user decision.

Regardless of the length of the Message, you can always see the button info.