Hoe je nuttige script- en codecommentaren schrijft

Je opent een script dat twee jaar geleden is geschreven — misschien door iemand die niet meer bij het bedrijf werkt, misschien door jezelf in haast voor een deadline. Er zijn 40 stappen, drie geneste If-branches, een loop die een subscript aanroept, en geen enkel commentaar dat uitlegt waarom iets ervan bestaat. Je moet nu gokken wat "Set Variable [$x; 1]" betekent, voordat je durft iets te veranderen.

Dit is een van de meest voorkomende — en gemakkelijkst vermijdbare — bronnen van verspilde uren in aangepaste zakelijke software. Goed commentaar is geen decoratie. Het is het verschil tussen een script dat tien jaar veilig kan worden onderhouden en een script dat helemaal opnieuw moet worden geschreven omdat niemand het nog vertrouwt. Dit artikel behandelt wat commentaar werkelijk bruikbaar maakt, met concrete voorbeelden uit FileMaker-scripting, ERP-aanpassingen en API-connectorcode — en waar AI-tools kunnen helpen, en waar niet.

Waarom eindigen zoveel scripts zonder enig commentaar?

Meestal is het geen luiheid — het is druk. Een script wordt onder deadline geschreven, het werkt, en de ontwikkelaar gaat naar het volgende ticket. Commentaar toevoegen voelt alsof het kan wachten. Maar het wordt nooit later toegevoegd, omdat het terugkeren om oude logica uit te leggen veel minder bevredigend is dan nieuwe logica schrijven.

Er is ook een mythe dat "goede code zichzelf documenteert." Schone naamgeving helpt, maar naamgeving kan alleen je vertellen wat een stap doet (Set Field [Invoice::Status; "Paid"]), nooit waarom het dat doet, welke bedrijfsregel het handhaaft, of welk randgeval het was geschreven om op te vangen. Dat ontbrekende "waarom" is precies wat later uren kost.

Wat maakt commentaar werkelijk nuttig — niet alleen aanwezig?

Commentaar verdient zijn plaats in het script als het één van deze beantwoordt:

• Waarom bestaat deze stap? Niet wat het doet — de veldnamen zeggen dat al.
• Welke bedrijfsregel of uitzondering wordt hiermee afgehandeld? bijv. "Ignore korting berekenen voor geannuleerde bestellingen — klant vroeg dit in ticket #482."
• Wat breekt als dit wordt gewijzigd of verwijderd? Een waarschuwing voor je toekomstige zelf of een collega.
• Welke aanname steunt deze code op? bijv. "Gaat ervan uit dat ShipDate nooit leeg is — afgedwongen door validatie op de Orders-layout."

Vergelijk deze twee opmerkingen bij dezelfde scriptsstap:

❌ // Set variable to 1

✅ // Flag $isRush = 1 wanneer de klant 'Next Day' verzending heeft geselecteerd. // Gebruikt downstream om de batchingstap over te slaan en de picklist onmiddellijk af te drukken.

De tweede versie betekent dat iemand die dit in drie jaar leest — tijdens een slappe periode wanneer 'Next Day'-bestellingen zeldzaam zijn en niemand deze logica meer onthouden — onmiddellijk zowel het doel als de gevolgen van het aanraken ervan begrijpt.

Wat moet je commentariëren — en wat moet je laten zitten?

Niet elke stap heeft commentaar nodig. Over-commentariëren is bijna net zo schadelijk als onder-commentariëren, omdat het de belangrijke opmerkingen in ruis begraaft en het lezen vertraagt.

Commentarieer dit:

• Elke branch die een bedrijfsregel codeert (prijsstelling, kortingen, goedkeuringsgrenzen, belastinglogica)
• Elke workaround voor een platformbeperking of een bekend bug
• Elke plek waar de "voor de hand liggende" oplossing bewust werd verworpen, en waarom
• Het ingangspunt van een script of subscript: wat triggert het, wat verwacht het als input, wat geeft het terug
• Elke hardcoded waarde die niet voor zichzelf spreekt (een magisch getal, een specifiek record-ID, een vaste vertraging)

Sla commentaar over voor:

• Stappen waar de veld- en variabelenamen al alles zeggen (Set Field [Customer::Email; $newEmail])
• Repetitieve, mechanische stappen zoals standaard error-trapping-boilerplate, zodra je team een gedeelde conventie hiervoor heeft
• Het restellen van precies wat de volgende regel doet in andere woorden

Hoe commentarieer je een scriptheader zodat iedereen het koud kan oppakken?

Een korte header bovenaan elk script of subscript betaalt voor zichzelf de eerste keer dat iemand anders dan de auteur het moet aanraken. Een goede header beantwoordt:

1. Doel — één zin: welk bedrijfsresultaat produceert dit script?
2. Trigger — wat roept dit script aan (een knop, een planning, een ander script, een webhook)?
3. Parameters — wat verwacht het als input, en in welk formaat?
4. Retourneert / bijwerkingen — wat wijzigt, maakt of verzendt het, en wat geeft het terug?
5. Afhankelijkheden — gerelateerde tabellen, externe API's of andere scripts waarvan het afhangt.
6. Laatste significante wijziging — datum en één regel, zodat mensen weten of het oud is.

Voorbeeld voor een FileMaker-script dat orders naar een ERP synchroniseert:

// DOEL: Nieuwe/bijgewerkte orders van FileMaker naar Exact Online via REST API pushen
// TRIGGER: Gepland script, wordt elke 15 minuten op de server uitgevoerd
// PARAMS: geen — leest alle Orders waarbij SyncStatus = "Pending"
// GEEFT TERUG: Stelt SyncStatus in op "Synced" of "Failed"; schrijft fouten naar SyncLog
// HANGT AF VAN: ERP_Connector-module, geldig OAuth-token in Config-tabel
// LAATST GEWIJZIGD: 2024-11 — logica voor opnieuw proberen toegevoegd voor 429 rate-limit-reacties

Dit enkele blok kan een nieuwe ontwikkelaar een uur besparen, alleen al om te begrijpen waar ze naar kijken.

Hoe verschilt commentaar in FileMaker van ERP- of API-integratiescode?

FileMaker-scripting is visueel en op stappen gebaseerd, dus opmerkingen leven als toegewijde "##"-commentaarstappen tussen actiestappen — ze moeten lezen als notities die het waarom tussen blokken wat uitleggen. Omdat FileMaker-scripts vaak lang zijn en sterk vertakken, is het groeperen van gerelateerde stappen onder één commentaarheader ("## Valideer klant vóór factuur aanmaken") vaak nuttiger dan commentaar op elke regel.

In ERP-aanpassingen en API-connectorcode (zeg, een script dat FileMaker-velden toewijst aan een ERP's REST-payload, of een webhook van een verzendprovider afhandelt), dragen opmerkingen meer gewicht omdat de logica minder visueel en meer over datavorm gaat. Hier commentarieer je de toewijzingsbeslissingen expliciet: waarom veld A aan veld B toewijst, wat er gebeurt met null-waarden, wat de API's eigenaardigheden zijn. Een opmerking zoals "// ERP verwerpt orders met leeg BTW-nummer — standaard ingesteld op '0000' voor privéklanten" voorkomt dat iemand die standaard gaat "repareren" en een hele categorie orders breekt.

Kunnen AI-tools je helpen betere opmerkingen te schrijven?

Ja, met een belangrijk voorbehoud. Een AI-assistent geïntegreerd in de ontwikkelaarsworkflow — iets als Klai gebruikt in FileMaker — kan echt nuttig zijn voor het opstellen van een eerste versie van een opmerking op basis van wat een scriptstap of berekening doet, of voor het opsporen van scripts die al te lang zonder commentaar zijn gegaan. Het is vooral goed in het uitleggen van wat onbekende code doet, wat waardevol is wanneer je een systeem erft.

Wat AI niet betrouwbaar kan is je zeggen waarom een bedrijfsregel bestaat — die context leeft bij de mensen die het hebben aangevraagd, niet in de code zelf. Behandel AI-gegenereerde opmerkingen als een nuttig concept dat een mens vervolgens corrigeert met de echte bedrijfsredenering, niet als een definitief antwoord. De beste praktijk: laat AI het commentaar suggereren, laat de ontwikkelaar die de bedrijfscontext kent het bewerken voordat het wordt gecommit.

Geldt dezelfde discipline ook voor lay-outs en interfaces, niet alleen scripts?

Ja — en het is gemakkelijk te vergeten. Wanneer je aangepaste formulieren of portals maakt, bijvoorbeeld met een lay-outtool als FmBetterforms, heeft de onderliggende logica (voorwaardelijke zichtbaarheidsregels, validatiescripts, veldberekeningen gekoppeld aan een formulier) dezelfde commentaardiscipline nodig als elk ander script. Een formulier dat een veld verbergt op basis van drie gestapelde voorwaarden is precies het soort logica dat onleesbaar wordt zonder een korte opmerking die de bedrijfsreden achter elke voorwaarde uitlegt.

Wat is een praktische commentaarcontrolelijst die je vandaag kunt toepassen?

• Heeft elk script een header die doel, trigger en afhankelijkheden uitlegt?
• Heeft elke bedrijfsregel-branch commentaar dat het waarom uitlegt, niet alleen het wat?
• Worden workarounds en bekende beperkingen duidelijk gemarkeerd, met een datum en reden?
• Worden magische getallen en hardcoded waarden uitgelegd?
• Heb je opmerkingen verwijderd die alleen het voor de hand liggende herstellen?
• Is er een gedeelde teamconventie voor commentaarstijl, zodat scripts consistent voelen tussen ontwikkelaars?
• Heeft iemand anders dan de originele auteur het script koud proberen te lezen, om te testen of de opmerkingen werkelijk helpen?

Veelgestelde vragen: Snelle antwoorden op veelgestelde commentaarvragen

Hoe vaak moeten opmerkingen worden bijgewerkt? Elke keer dat de logica die ze beschrijven verandert. Een oud commentaar dat oud gedrag beschrijft is erger dan geen commentaar, omdat het actief misleidt.

Moeten opmerkingen FileMaker-specifieke syntaxis uitleggen? Nee — ga ervan uit dat de lezer het platform kent. Commentarieer de bedrijfslogica, niet het gereedschap.

Loont het het werk om commentaar in oude, werkende scripts in te voegen? Alleen wanneer je dat script al om een ander reden aanraakt. Het commentariëren van een script dat je niet wijzigt verspilt tijd die beter ergens anders kan worden besteed — maar op het moment dat je het opent om het te repareren of uit te breiden, voeg je de ontbrekende context toe voordat je gaat.

Wie is verantwoordelijk voor commentaarkwaliteit — de ontwikkelaar of een reviewer? Beiden. De ontwikkelaar schrijft de eerste versie terwijl de context vers is; een code review-stap (zelfs informeel, een ander persoon die het leest) vangt gaten op die de auteur niet had opgemerkt dat ze waren achtergelaten.

Goed commentaar is eigenlijk een vorm van institutioneel geheugen — het laat kennis overleven personeelswisseling, platformupgrades en de eenvoudige gang van tijd. Dit is precies het soort discipline dat aangepaste software die tien jaar betrouwbaar blijft onderscheidt van software die stiekem in een black box verandert waar niemand aan durft te raken, een thema dat breder wordt verkend in Loggix's gids over hoe je aangepaste zakelijke software betrouwbaar en overdraagbaar maakt. Als je een FileMaker-systeem, een ERP-aanpassing of een set API-connectors erft die zich meer als een black box voelen dan als een hulpmiddel, kan Loggix je helpen te beoordelen wat er is, de ontbrekende documentatie opnieuw op te bouwen, en — waar het logisch is — AI-ondersteuning of een praktische consultatiesessie inbrengen om een systeem in kaart te brengen dat de volgende ontwikkelaar werkelijk kan vertrouwen.