Documentatie volgens wettelijke regels: de zaak van de labapplicaties

Een maker van wetenschappelijke apparatuur had, in de loop van jaren, tal van applicaties gemaakt voor gebruik in een laboratorium. Soms ging het daarbij om het uitvoeren van berekeningen, soms ook om de besturing van apparatuur in het lab. Wat de applicaties gemeen hadden was het totale gebrek aan documentatie. Onderhoudbaarheid begon een probleem te worden. Bovendien waren er kritische kanttekeningen gekomen van het accreditatieinstituut. Voor hen was de software een zwarte doos waarvan ze de werking op goed vertrouwen moesten aannemen.

Wat we deden

We produceerden een complete set documentatie op basis van een gemeenschappelijke opzet. De documenten beschrijven wat elke applicatie doet en hoe hij kan worden onderhouden.

Tot we aan het werk begonnen, had niemand anders dan de programmeurs ooit de code gelezen. We kwamen dan ook tal van mogelijke verbeterpunten tegen in de programmatuur zelf. Zo vonden we routines die nergens werden aangeroepen, routines die (bijna) identiek waren aan andere, en "classes" die telkens opnieuw waren gedefinieerd. Wanneer we zoiets tegenkwamen, lieten we het de klant weten en wachtten op zijn beslissing. Vaak bestond die uit een wijziging van de programmacode.

Hoe we het deden

Eerst werd een stramien opgesteld op basis van de IEEE Std 1016-1998 (zie Notities). Daarna beschreven we de verschillende applicaties en pasten die in het stramien. Als we iets tegenkwamen wat problemen kon geven, merkten we dat op. We beschreven ook alle formules en vergelijkingen die in de software werden gehanteerd. Voor zo ver mogelijk namen we steeds een verwijzing op naar de wetenschappelijke publicatie waarin zo'n formule of vergelijking werd beschreven.

De applicaties waren indertijd allemaal geschreven zonder dat zelfs maar een functionele beschrijving aanwezig was. Bijna al ons werk was daarom gebaseerd op het doorspitten van de broncode. Als je het aantal regels code deelt door de tijd die we nodig hadden, kom je uit op zo'n 800 regels code gedocumenteerd per dag.