How to write useful script and code comments

You open a script that was written two years ago — maybe by someone who no longer works at the company, maybe by yourself in a hurry before a deadline. There are 40 steps, three nested If branches, a loop that calls a subscript, and not a single comment explaining why any of it exists. You now have to guess what "Set Variable [$x; 1]" is for, before you dare change anything.

This is one of the most common — and most avoidable — sources of wasted hours in custom business software. Good comments are not decoration. They are the difference between a script that can be safely maintained for ten years and one that has to be rewritten from scratch because nobody trusts it anymore. This article walks through what actually makes a comment useful, with concrete examples from FileMaker scripting, ERP customizations, and API connector code — and where AI tools can help, and where they can't.

Why do so many scripts end up with no comments at all?

Usually it's not laziness — it's pressure. A script gets written under deadline, it works, and the developer moves on to the next ticket. Commenting feels like it can wait. But it never gets added later, because going back to explain old logic is far less satisfying than writing new logic.

There's also a myth that "good code documents itself." Clean naming helps, but naming can only tell you what a step does (Set Field [Invoice::Status; "Paid"]), never why it does it, what business rule it enforces, or what edge case it was written to catch. That missing "why" is exactly what costs hours later.

What makes a comment actually useful — not just present?

A comment earns its place in the script if it answers one of these:

• Why does this step exist? Not what it does — the field names already say that.
• What business rule or exception does this handle? e.g. "Skip discount calculation for cancelled orders — client requested this in ticket #482."
• What will break if this is changed or removed? A warning for your future self or a colleague.
• What assumption is this code relying on? e.g. "Assumes ShipDate is never blank — enforced by validation on the Orders layout."

Compare these two comments on the same script step:

❌ // Set variable to 1

✅ // Flag $isRush = 1 when the customer selected 'Next Day' shipping. // Used downstream to skip the batching step and print the pick list immediately.

The second version means someone reading it in three years — during a slow season when "Next Day" orders are rare and nobody remembers this logic — instantly understands both the intent and the consequence of touching it.

What should you comment — and what should you leave alone?

Not every step needs a comment. Over-commenting is almost as harmful as under-commenting, because it buries the important notes in noise and slows down reading.

Comment these:

• Any branch that encodes a business rule (pricing, discounts, approval thresholds, tax logic)
• Any workaround for a platform limitation or a known bug
• Any place where the "obvious" solution was deliberately rejected, and why
• The entry point of a script or subscript: what triggers it, what it expects as input, what it returns
• Any hard-coded value that isn't self-explanatory (a magic number, a specific record ID, a fixed delay)

Skip commenting:

• Steps where the field and variable names already say everything (Set Field [Customer::Email; $newEmail])
• Repetitive, mechanical steps like standard error-trapping boilerplate, once your team has a shared convention for it
• Restating exactly what the next line does in different words

How do you comment a script header so anyone can pick it up cold?

A short header at the top of every script or subscript pays for itself the first time someone other than the author has to touch it. A good header answers:

1. Purpose — one sentence: what business outcome does this script produce?
2. Trigger — what calls this script (a button, a schedule, another script, a webhook)?
3. Parameters — what does it expect as input, and in what format?
4. Returns / side effects — what does it change, create, or send, and what does it hand back?
5. Dependencies — related tables, external APIs, or other scripts it relies on.
6. Last significant change — date and one line, so people know if it's stale.

Example for a FileMaker script that syncs orders to an ERP:

// PURPOSE: Push new/updated orders from FileMaker to Exact Online via REST API
// TRIGGER: Scheduled script, runs every 15 minutes on the server
// PARAMS: none — reads all Orders where SyncStatus = "Pending"
// RETURNS: Sets SyncStatus to "Synced" or "Failed"; writes errors to SyncLog
// DEPENDS ON: ERP_Connector module, valid OAuth token in Config table
// LAST CHANGED: 2024-11 — added retry logic for 429 rate-limit responses

This single block can save a new developer an hour of tracing logic just to understand what they're looking at.

How is commenting different in FileMaker versus ERP or API integration code?

FileMaker scripting is visual and step-based, so comments live as dedicated "##" comment steps between action steps — they should read like sticky notes explaining the why between blocks of what. Because FileMaker scripts are often long and branch heavily, grouping related steps under a single comment header ("## Validate customer before creating invoice") is often more useful than a comment on every line.

In ERP customizations and API connector code (say, a script that maps FileMaker fields to an ERP's REST payload, or handles a webhook from a shipping provider), comments carry more weight because the logic is less visual and more about data shape. Here, comment the mapping decisions explicitly: why field A maps to field B, what happens with null values, what the API's quirks are. A note like "// ERP rejects orders with empty VAT number — default to '0000' for private customers" prevents someone from "fixing" that default and breaking a whole category of orders.

Can AI tools help you write better comments?

Yes, with an important caveat. An AI assistant embedded in the development workflow — something like Klai used inside FileMaker — can be genuinely useful for drafting a first-pass comment based on what a script step or calculation does, or for spotting scripts that have gone comment-less for too long. It's especially good at explaining what unfamiliar code does, which is valuable when you inherit a system.

What AI can't do reliably is tell you why a business rule exists — that context lives with the people who requested it, not in the code itself. Treat AI-generated comments as a useful draft that a human then corrects with the real business reasoning, not as a final answer. The best practice: let AI suggest the comment, let the developer who knows the business context edit it before committing.

Does the same discipline apply to layouts and interfaces, not just scripts?

Yes — and it's easy to forget. When you build custom forms or portals, for example with a layout tool like FmBetterforms, the underlying logic (conditional visibility rules, validation scripts, field calculations tied to a form) needs the same commenting discipline as any script. A form that hides a field based on three stacked conditions is exactly the kind of logic that becomes unreadable without a short note explaining the business reason behind each condition.

What's a practical commenting checklist you can apply today?

• Does every script have a header explaining purpose, trigger, and dependencies?
• Does every business rule branch have a comment explaining the why, not just the what?
• Are workarounds and known limitations flagged clearly, with a date and reason?
• Are magic numbers and hard-coded values explained?
• Have you removed comments that just restate the obvious?
• Is there a shared team convention for comment style, so scripts feel consistent across developers?
• Has anyone other than the original author tried to read the script cold, to test whether the comments actually help?

FAQ: Quick answers to common commenting questions

How often should comments be updated? Every time the logic they describe changes. A stale comment that describes old behavior is worse than no comment, because it actively misleads.

Should comments explain FileMaker-specific syntax? No — assume the reader knows the platform. Comment the business logic, not the tool.

Is it worth retrofitting comments into old, working scripts? Only when you're already touching that script for another reason. Commenting a script you're not modifying wastes time better spent elsewhere — but the moment you open it to fix or extend it, add the missing context before you leave.

Who should be responsible for comment quality — the developer or a reviewer? Both. The developer writes the first pass while the context is fresh; a code review step (even informal, a second person reading it) catches gaps the author didn't notice they'd left.

Good comments are really a form of institutional memory — they let knowledge survive staff turnover, platform upgrades, and the simple passage of time. This is exactly the kind of discipline that separates custom software that stays reliable for a decade from software that quietly turns into a black box nobody wants to touch, a theme explored more broadly in Loggix's guide on how to make custom business software reliable and transferable. If you're inheriting a FileMaker system, an ERP customization, or a set of API connectors that feel more like a black box than a tool, Loggix can help you assess what's there, rebuild the missing documentation, and — where it makes sense — bring in AI assistance or a hands-on consultancy session to map out a system that the next developer can actually trust.