Seven Ways FileMaker Can Speak for You

October 30, 2024
Admin Admin

or, Why are there so many FileMaker applications with zero commenting??

There are at least seven places within a FileMaker application to place comments so other programmers will know what the intention was with an application.

At HighPower Data Solutions, we’ve been doing FileMaker consulting and development for a long time. Because of this, we are often asked to work on applications which have been developed by other programmers. In some cases, they’re what Claris calls ‘citizen developers’ and in others they’re full-fledged FileMaker developers. But, unfortunately, many times, there are no notes or comments within the solution. For us, this isn’t an insurmountable problem. It’s more of an annoyance. But for the client, it is a problem because it ends up costing them more money since it takes us time to review those scripts, test them, and figure out exactly what the previous developer was attempting.

Although many applications have zero commenting, it’s really unnecessary because FileMaker provides lots of methods for communicating what is happening within the solution. This article will highlight the many ways a developer can make a FileMaker application tell the world about itself.

There’s a joke among programmers that you should comment your scripts as though the next developer has an anger problem and he knows where you live! Whatever the motivation, every script should be well-commented to make debugging faster. So here’s a list of how to use FileMaker’s internal tools to comment and share and about a solution.

Seven Ways to Make FileMaker Speak for You

1. Script commenting

This is the most well-known option for developers. FileMaker scripts have a comment line to explain what is going on with the application.

Here are a few guidelines for script commenting:

a. Every script should have a header comment section of several lines to explain the big picture.

This is the most important part. Before the script code, there should be an explanation which includes the following parts:

  • Purpose – What does the script do?
  • Context – List the Table, Layout, Portal, Tab, and Field where the script operates. Include anything of significance.
  • Initiated By – What activates the script? A button? A script trigger? A subscript call from another script?
  • Inputs / Dependencies – What does the script require to run? A JSON command? Global variables?
  • Results – What will be the effect of the script?
  • General Notes – Any other important points can be mentioned in the Notes field.
  • History – It’s not a single line, but a list of all the major changes to the script. This is helpful to future developers, who might think of trying something which has already been done. At HighPower, our history notes take this form: YYYY-MM-DD | Developer’s Initials | Description of the changes made.

Now, you don’t have to fill out every one of these lines; just the ones that matter. And there’s no need to do this on short, simple scripts. This is for the complex scripts with a lot of lines.

I learned the hard way the importance of script commenting on my very first professional FileMaker job. I was hired by a company to update a report which had been developed by a previous developer. Whether he was an internal company dev who had left or an external dev, I never learned. But when I opened that script up to examine it, it was the longest script I had ever seen in my short development life. But it turns out, that 20 years later, it still was the longest single script I have seen. When I printed it out, it took up 17 pages of 8.5 x 11 inch paper!

And there wasn’t a single comment in the entire thing!

As a young FileMaker developer, I had no idea what this script was trying to do. So I just started to walk through the script with the script debugger. It took forever for each pass. And I had to do it repeatedly until I understood it. My work would have been easier, and the cost would have been less for the client, if the previous developer had commented. (And unfortunately, I didn’t know where he lived!)

b. Major sections within the script should be clearly separated and commented.

At HighPower, we separate our code–for the lengthy scripts–into three parts: Setup, Main, and Cleanup.

  • Setup – make sure you are in the right context, layout, and field. Then confirm you have all dependencies, such as variables defined and ready.
  • Main – this is the bulk of the code, where the primary work is performed
  • Cleanup – just the title of this section is a reminder to our developers to clear out those global variables, and get the user back into the context they started with.
  • Other sections – if you have a long script, then make use of Comments to add blank lines, asterisks, rows of lines, dashes, or equal signs to separate important sections. Make good use of white space–which is free!–to make your scripts readable.

c. Tricky lines of code should be explained in terms of what is being attempted.

If you’re doing something unique, it may be good to let the next developer know what you’re trying to do. In many cases, the next developer may be you! There are times when I’ve reviewed my own code weeks or months later, and if I had not commented, I wouldn’t have understood it!

d. References to external plugins or file references should be commented

If those plugins or files become separated from the original file / script in some way, you will not see anything except a ‘missing plugin’ warning. If you didn’t comment your script like “Base Elements plug here, using the SMTP function”, you may be clueless about how to repair it.

So, that is Script Commenting. It is the largest and most important tool at your disposal for writing excellent code.

2. Field commenting

When you create a script in the tables layout, there’s a “Comment” field underneath the “Field Name” section. Use this. If the purpose of a field is not immediately obvious, or if the field could be confused with some other similar field, then comment it. At HighPower, we put our initials, the date, and fields’s purpose in the Comments section. It helps! You don’t have to use it every time; just when some additional clarity may be needed.

3. Calculation Engine commenting

FileMaker developers know that even with the calculation engine of a calc field, you can comment by using the “//” symbols. Use this too. Explain what is happening, or should be happening. For complex calculations, like IFs or CASE statements, comments can be a lifeline.

For one client, the previous dev had created a massive LET statement, six pages long. Fortunately, he had commented, so I was able to work out the logic flow and edit it as needed.

4. Relationship Graph commenting

The relationship graph is a great place to provide comments. In fact, Claris has prepared for this by providing a notes tool right in the RelGraph. Click the “A” icon to create a note in the RelGraph.

Here’s a sample of the guidance we provide in the RelGraph to explain our color-coding of the table occurrences:


5. Documentation Folder

For large, complex solutions, we create a folder in the Scripts Workspace called “Documentation”. We fill it with non-functions ‘scripts’, which are all comments, describing various parts of the solution that require further explanation.

6. Tooltips

This tool not only helps other developers, but it also assists the Users in understanding what the solution should be doing. So let FileMaker speak for you to the User! User Tooltips liberally throughout the solution. Explain the purpose of buttons, unique fields, scripts, and reports. Explain what is supposed to be happening. Your customers will be grateful.

7. Placeholder Text

This same principle applies to placeholder text. Put an explanation of what kind of data should be entered in the field. Don’t assume the user will be able to figure it out. Why make them wonder? If there’s any doubt, explain what is expected.

Example of field place holder

FileMaker is a fabulous application. Thousands of great FileMaker developers use it to help businesses succeed. We celebrate with everyone who loves this beautiful product as much as we do. We want to see them increase and prosper. We believe the entire platform can be enhanced and receive more recognition from the world if us developers do our part in commenting. If we let FileMaker speak for itself to other developers and users, then it will be a more pleasant user experience for everyone. Business will prosper and so will the FileMaker community.

William Miller,
President of HighPower Data Services,
HighPowerData.com