Claris FileMaker is a powerful tool for creating automated workflows; workflows that not only make our workplaces productive but also ensure accuracy and consistency within our business processes. When you think about it, each of our scripted workflows encapsulates a vital piece of our organization's tribal knowledge. FileMaker applications are typically created, extended and maintained by the very process experts that use them, which isn't usually the case with other software development platforms. So our FileMaker apps easily become a projector of our business goals and operations.
The FileMaker Script Workspace is the location where a lot of automation and optimization takes place. FileMaker’s easy to understand, drag and drop, point and click, modular method of creating scripts allows business process experts to “code” like their technical colleagues in IT, without many of the hassles of learning low-level programming languages. Users creating scripts can focus on solving the business challenge in front of them instead of the technical one. Having said all that, FileMaker hasn’t eliminated all the aspects of writing code. As you create more and more complex scripts that do more and more things, you need to step back and make sure the business process you're modeling or the task you're automating isn’t being lost in the malaise of Set Fields, Loops and If Statements.
Why ask why?
Here's a scenario, you created a script that allows your accounts receivable staff to view overdue invoices quickly. Now that might seem like a simple task, but payment terms can vary by customer. New customers may have shorter payment windows than established customers. And, maybe your organization is very forgiving to non-profit customers who are a little late with payments. The script can accommodate these different conditions. But, how do we ensure that we'll understand all of the exceptions and special cases when we look at the script a month or a year later? Of course, we'll want to know why the developer included specific elements and why we loop through certain invoices only to omit some of them. And, it would be especially important to know who told the developer it was okay to do that in the first place. Thanks to FileMaker's fairly transparent scripting language – if you can even call it a language – most folks can figure out what the script does with no direct knowledge and minimal effort. But, few of us can confidently explain why it does what it does.
This problem compounds if the original creator of the script or the business process expert who inspired it is either no longer available to explain the why or can’t quite remember the details. Now some of the details can be handled with proper data modeling, but in the real world, they are often encased in a script, the Swiss Army knife in the FileMaker toolset. So how do we solve this problem? Well, the solution is a script step called Comment. Just as the pen is mightier than the sword, the Comment step can be more powerful than the Loop, If and Insert from URL script steps combined, when used correctly. Why is the Comment step so powerful? Because it's the one part of a script that can tell you why you're doing something. It has the power to tell the harried person who is trying to debug a script what the script is supposed to do, when it's misbehaving and why it's doing one thing and not another.
We've laid the groundwork as to why it makes sense to use the Comment step; next, we have to wrap our heads around when and how to apply its unique powers. There are a lot of ways we use the Comment step. We can use it as a mechanism to track changes, expose dependencies and explain the why, which is what we intend to highlight in this article. It bears repeating that the FileMaker scripting language is pretty transparent in its operation. It's relatively easy to determine what's being done and where because FileMaker is very context-focused. The program allows us to choose from a defined list of commands and then explicitly tell it where (the context) to act. There are even several commands that require you to get to the right place first. Although, it's often easy to see what the script is doing, it's rarely apparent why it's doing it.
Why does why matter? Well, for one thing, we eventually revisit the workflows we create when we find a better way to do something and we want to modify the script to reflect that. We need to know why it did the things it used to do, so we don't inadvertently break something in our dash to improve stuff. Another reason could be a workflow that is complex or infrequently runs that we want to extend or troubleshoot. Again, it probably won't be hard to figure out what it's doing, but we might be confused about why it's doing it. This could ultimately lead us to modify key elements of the script incorrectly. Or, we completely change the purpose of the script based on what we assume the script should be doing. More often than not, the process expert who created the script is no longer accessible. And, without the script comment to explain it, it will be difficult to figure out the real purpose of the script.
How To Comment
So now that we've established the importance of "why," how do we incorporate it into our scripts? The first thing we can do is to start explaining the purpose of the script by writing it out as comments first.
Next, flesh out the action steps in the appropriate locations and update the comments accordingly. This method has the added benefit of helping plan the script while documenting it in one fell swoop. If you focus on the action portion of the script and plan to add your comments after, you might forget why you arranged the script in that particular way or move on to other pressing issues. So the script will be functional for the moment but not necessarily helpful to yourself or others later.
And when you modify or extend a script, be sure to add or update the comments as you go, while the "why" is fresh in your mind. Be careful not to leave anything out, always assume the future you will have forgotten all the particulars. We think it's better to be too specific than too general.
We've only touched on one aspect of commenting. There are plenty of other ways you can use it. However, we strongly recommend using comments to explain the less obvious details of a function. This could be as simple as a comment at the top of the script stating its purpose, along with explanations peppered throughout like road signs on a deserted country road.
Be sure to review our strategic recommendations for writing and maintaining FileMaker scripts. And learn how FileMaker subscripts improve productivity. You can find more helpful FileMaker developer resources here.
This article is also published on FileMakerProGurus.com.
