This article will show examples of good comments vs. bad comments, and how you can improve your code readability by following a few key principles. In our previous blog posts on code readability, we showed how to enhance code readability by using spacing and meaningful naming without adding comments.
Some of you might be wondering, what’s wrong with comments?
Accurate, well-placed, informative, and intention-revealing comments are good; however, most comments are not this way.
Why are most comments bad?
Most comments are bad because developers can’t realistically maintain them. Over time, comments can become inaccurate and misleading, which is worse than not having comments.
Not all comments need to be there. Often, we write a bunch of script steps that we know are confusing and disorganized, so we add comments to make our script more readable.
How does this affect our code?
What we are doing is creating two narratives for our scripts; one lives in the script steps, and one lives in the comments. If the narrative that lives in the script steps is unclear and not expressive, we attempt to compensate for it by creating another one.
Between the two narratives, only one of them contains the truth, which is the one that will be executed by your solution, your script steps. As time goes on, the narrative captured by comments might become inaccurate, and eventually, become lies.
Let’s look at some examples of good comments vs. bad comments.
Types of Bad Comments
Redundant Comments
Look at the comment above that says New Window right before an actual New Window script step. It’s obviously redundant.
But what about this “Find the project” comment in front of four script steps performing a find? It must be providing some value by using one row to tell you what the next four rows are doing, right? Not really. This comment is not more informative than the script steps themselves, so there’s no need to add it.
Comments that aren’t intention-revealing
Let’s look at this comment that says, “Project ID must be added to the script parameter when creating a new project.” The meaning of this comment might be clear in the head of the developer who wrote this, but it’s not obvious to others. This comment seems to be telling some rules, but it doesn’t explain the reason behind the rule or what purpose this rule serves.
This step makes sure that when it is called a second time in the same workflow, the new project created the first time will be found so that the user can resume editing. So we should say something along that line, like “Make sure the project created can be found when the script is called again.“
Misleading comments
Misleading comment
This comment above is misleading, the script opens up a new window and navigates the user to a layout based on the project context. However, when the script ends, it closes the new window. So it doesn’t guarantee to put the user in any specific context.
Other developers will see this comment and assume that when the script finishes, they will be in the project context. They might write some additional features to run after this script that depends on the project context, and then they will be sorry.
In this case, instead of removing the comment, I’ll correct it, because context is very important in FileMaker. Announcing your start and end context makes it much easier to interface your script with others’ development work.
Corrected comment
Commented-out script steps
Yes, we’ve all created this at some point. Commented-out script steps make people wonder why they are commented out. Are they important? Were they left there as a reminder for something? How long have they been there?
If you are scared of deleting commented code because you don’t want to lose work, save a copy of your file or create a DDR; there’s no need to hoard these comments in your solution.
Comments containing nonlocal information
Check out the line that says if the employee to assign doesn’t exist, the user can create the employee and then assign it to the project. It is saying something informative, but why is it here? It should probably be moved up, right below the “Else If [$userAction = “Add Assignee”] line to explain what this entire branch is doing. Or, perhaps it should be removed as the branching condition itself is quite informative.
Comments should describe adjacent script steps. Don’t offer system-wide or out-of-context information using comments.
Comments containing too much information
When I said a good script should read like a well-written article, I don’t want to encourage developers to actually write articles in their script using comments. Overall, if you can use meaningful naming and spacing to express something, don’t use comments, and don’t comment on bad code. Just rewrite it.
OK, enough with bad comments. Let’s look at some good ones.
Types of Good Comments
Informative comments
This header comment summarizes 14 lines of content
I like to use these comments in front of a block of script steps. I call them block headers. They are supposed to summarize what a large block of code is intended to do, which helps the reader comprehend the script’s workflow and locate the script steps they are looking for.
Explanation of intent
After rewriting one of our bad comments, it now reveals the intention of the writer. It’s a good comment now.
Warning of consequences
Sometimes it is useful to warn others about certain consequences. But do be mindful about using comments this way. If you find yourself having to constantly write warning comments, perhaps consider rearchitecting your code so it’s less dangerous.
Journal comments
If this was any other technology that can leverage modern version control software to manage changes, journal comments will be completely redundant. But since FileMaker can’t do that, I’ll leave it here as good ones.
Final Result
By adding meaningful comments, our script is now much cleaner than the script we started with. These comments, strategic spacing, and naming conventions have improved our code readability. We hope that this analysis of good vs. bad comments is useful for your development skills.
If you prefer to learn in video format, check out our video on Good Comments vs. Bad Comments.
*This article was originally written for AppWorks, which has since joined Direct Impact Solutions. This article is intended for informative purposes only. To the best of our knowledge, this information is accurate as of the date of publication.