Script documentation standards for FileMaker solutions
ExpertWrite in-script comment blocks and external documentation that enables any developer to understand, maintain, and safely modify a script they did not write.
What you'll learn
- A standard header comment block format for FileMaker scripts
- How to document intent vs implementation within script steps
- How to mark deprecated scripts and their replacements
- How to document edge cases and known limitations in comments
- How to document scripts that run with full access privileges
Undocumented FileMaker scripts are a maintenance liability. When the original developer is unavailable, a script without comments forces the maintainer to reverse-engineer intent from implementation -- a slow and error-prone process. A standard documentation format applied consistently across all scripts makes any script readable to any developer in minutes.
The standard script header comment block
Every script should begin with a block of comment steps that describe: the script's purpose in one sentence, expected parameter shape, return value shape, the privilege context (runs with full access or caller's privilege), last modified date and by whom, and any dependencies (scripts it calls, tables it touches).
# ===========================================================
# Script: Invoice - Commit
# Purpose: Validate and save the current invoice record.
# -----------------------------------------------------------
# Parameter (JSON):
# invoiceID (string, required) -- FileMaker record ID
# skipValidation (boolean, optional) -- default false
#
# Returns (JSON):
# { "success": true, "invoiceID": "..." }
# { "success": false, "error": "...", "code": 500 }
#
# Privilege: runs as caller; does NOT use full access
# Dependencies: Util - Translate Error
# Modifies tables: Invoices
# -----------------------------------------------------------
# Last modified: 2026-04-30 by Agnes Riley
# Change: Added record-lock retry logic (error 301)
# ===========================================================Sign in to track your progress and pick up where you left off.
Sign in to FM Dojo