Het documenteren van software
Als we een modelscan uitvoeren komt het onderwerp documentatie altijd aan bod. En meestal is het een pijnlijk onderwerp. Iedereen begrijpt dat goede documentatie essentieel is voor het soort complexe programmatuur waarin VORtech gespecialiseerd is. Maar niemand vind het leuk om te maken en meestal is de documentatie verouderd en onvolledig. Wat is essentieel bij het documenteren van software en wat kan achterwege blijven?
Hoe het documenteren van software niet moet
Laten we eerst eens kijken naar een paar voorbeelden van hoe het niet moet.
- De documentatiefundamentalist
Je weet meteen dat je hiermee te maken hebt als er iemand naar je toekomt met een steekkarretje mappen die ieder duizenden pagina’s aan documentatie bevatten. In dit geval is de benadering dat elk detail van de code op elk niveau van abstractie gedocumenteerd moet zijn. Alleen al de hoeveelheid maakt deze documentatie grotendeels waardeloos. En het onderhouden ervan vraagt een enorme inspanning. Dat geld kun je je beter besparen, tenzij je software voor een ruimteschip maakt waarbij een rigoureuze aanpak essentieel is.
- Het agile type
Er is niets mis met agile als het goed gedaan wordt. Maar soms wordt het gebruikt als excuus om geen behoorlijke documentatie te maken. De eerste sprint levert een algemeen ontwerp op, maar dat wordt nooit meer geupdate omdat voortschrijdend inzicht alles toch weer anders maakt. Aan het eind van het project heb je dan inconsistente documentatie die in het beste geval nauwelijks behulpzaam is. - De documentatiehater
Waarschijnlijk zullen de meeste ontwikkelaars zich wel in deze term herkennen, maar hier bedoel ik eigenlijk het soort mensen die luidkeels verkondigen dat elke documentatie zonde van de tijd is. Volgens deze mensen hoef je alleen maar clean code te maken en dan ben je klaar. Ook hier geldt weer: clean code is een prachtig idee maar elke code van een serieuze omvang heeft toch echt meer nodig dan dat. Iemand die de code voor het eerst ziet moet een algemeen idee hebben van de architectuur en principes. En nog wel meer ook om te voorkomen dat ze eindeloos moet gaan rondklikken in de code om te begrijpen wat er gebeurt.
Welke documentatie is er nodig?
De bovenstaande voorbeelden lijken misschien wat overdreven. Maar eerlijk gezegd is de werkelijkheid vaak niet heel veel anders. Wat is de ‘juiste’ documentatie? In mijn ervaring is dat het volgende:
- Modellen en algoritmen
De term model is wat verwarrend in deze context. Ik doel hier niet op het model van software (als in model based software development) maar op het wiskundige model dat in de code wordt doorgerekend. Dit soort documentatie is uniek voor berekeningssoftware en staat meestal vol formules, afleidingen en verwijzingen naar wetenschappelijke literatuur. Dit document is essentieel, niet alleen om de code te begrijpen maar ook om te bepalen wat er wel en niet mee berekend kan worden.
Deze documentatie is vaak statischer dan de code zelf. Het wiskundige model en de belangrijkste algoritmen veranderen niet zo vaak. - Gebruikershandleiding
Hopelijk gaat iemand jouw applicatie gebruiken. Als je dat niet zelf bent, dan is een goede gebruikersdocumentatie essentieel. Meestal is het goed om die te laten schrijven door iemand die niet betrokken was bij de ontwikkeling als zodanig. Anders is er een risico dat de documentatie dingen mist die vanzelfsprekend zijn voor jou maar niet voor een gebruiker die er voor het eerst mee werkt.
Een aspect van gebruikersdocumentatie dat specifiek is voor complexe rekenprogrammatuur, is de achtergrond van de modellering en algoritmiek. Dat hangt uiteraard samen met het bovengenoemde document (Modellen en Algoritmen) maar je wilt de gebruiker niet lastig vallen met alle details en wiskundige afleidingen. Ze hoeft eigenlijk alleen genoeg weten om te kunnen bepalen wat ze wel en niet met de applicatie kan doen. Het schrijven van dit stuk moet gebeuren door iemand die zowel de gebruiker als de ontwikkelaar snapt. Dat soort mensen is zeldzaam.
- Architectuur
Het derde essentiële document is de architectuurbeschrijving. Met architectuur bedoel ik dan alles wat een goed overzicht geeft over de structuur van de code. Er zullen mensen zijn die daar wat strakker in zijn, maar ik hoop dat ze me dit losse gebruik van de term zullen vergeven. Ik noem dit vaak de landkaart van de applicatie omdat het de ontwikkelaar helpt om zijn weg te vinden in de code, net zoals bij een echte landkaart. Sommige mensen zouden dit een model van de code noemen, maar die term reserveer ik in deze blog voor de modellen die bedoeld worden onder het eerste punt.
Het is het mooiste als deze documentatie in een formeel framework wordt beschreven omdat dat ervoor zorgt dat de documentatie compleet en concreet is en omdat de betekenis van alle symbolen dan goed gedefinieerd is. Soms is het zelfs mogelijk om direct een raamwerk voor de code te genereren uit deze documentatie maar in mijn ervaring is dat minder nuttig voor het soort rekenintensieve toepassingen waarin wij gespecialiseerd zijn. Maar een formele architectuurbeschrijving is niet per se nodig: een eenvoudige PowerPoint presentatie met gekleurde rechthoeken is vaak net zo behulpzaam.
Soms zijn interactie diagrammen ook handig op dit niveau. Dit speelt vooral bij toepassingen die bestaan uit losjes gekoppelde componenten, zoals bij een microservices architectuur.
Ook dit soort documentatie verandert niet vaak. Alleen bij een grote herstructurering van de code moet het worden aangepast, maar dat gebeurt meestal zelden. - Programmeerrichtlijnen
Een nuttige applicatie kan heel lang bestaan. We komen soms toepassingen tegen waarvan de ontwikkeling in de jaren 80 van de vorige eeuw begonnen is, dus zo’n 30 jaar geleden. Zulke applicaties zijn ontwikkeld door meerdere generaties ontwikkelaars. Om de code consistent te houden zijn programmeerrichtlijnen essentieel. Dat omvat codestandaarden (hoe je variabelen en classes een naam geeft, hoe je omgaat met errors, omgevingsvariabelen, etc.), gebruikte tools en de teststrategie. De meest bedrijven hebben daar standaard documenten voor maar de programmeerrichtlijnen zijn een integraal deel van de documentatie van de applicatie. Als de ontwikkeling ervan naar een andere groep of een ander bedrijf gaat dan moeten de programmeerrichtlijnen mee.
- Codedocumentatie
De rest van de documentatie wordt niet expliciet ontwikkeld maar wordt gegenereerd uit commentaar in de code. Dat commentaar moet dan natuurlijk wel goed gestructureerd zijn zodat er nette documentatie uit gegenereerd kan worden. Tegelijkertijd moet het commentaar ook zinvol zijn in de code als zodanig. Als het goed is, vult deze documentatie het gat tussen de architectuurbeschrijving en de code.
In de codedocumentatie vind je typisch de syntax en semantiek van classes, structures en methods in de code. In veel gevallen hoef je deze documentatie niet eens te genereren omdat de ontwikkelaar toch direct in de code kijkt. Alleen als je een library ontwikkelt is het waarschijnlijk zinvol om de codedocumentatie te converteren naar een klikbare HTML-pagina van de classes en methods.
Een paar handige tools
Het is altijd slim om het ontwikkelproces zoveel mogelijk te automatiseren. Dat geldt zeker ook voor het onderhoud van de documentatie. Zeker de meer laag niveau delen van de documentatie lenen zich heel goed voor documentatie.
De bekendste tool hiervoor is waarschijnlijk Doxygen. Dat is een tool die mooie documentatie genereert uit het commentaar in de code. Je zult je even vertrouwd moeten maken met de manier waarop Doxygen het commentaar gebruikt en welke trucs je kunt uithalen om leesbare documentatie te krijgen. Zodra je dat weet en consistent toepast, krijg je zowel mooie documentatie als goed geannoteerde code. Doxygen is oorspronkelijk ontwikkeld voor C-achtige talen maar tegenwoordig worden de meeste andere gangbare talen ook ondersteund zoals Python en zelfs Fortran. Ik weet niet hoe goed de Fortran versie werkt, anders is Fordocu een goed alternatief.
De laatste tijd is Sphinx een tool die veel aandacht trekt. Het is de standaard tool om Python documentatie te maken. In theorie kun je er ook andere talen mee documenteren maar dat is vooralsnog niet eenvoudig en het maakt de code er ook niet leesbaarder op. In een andere blog laten we zien hoe Sphinx gebruikt kan worden in het softwareontwikkelproces met CMake.
Voor sequencediagrammen is Typora een mooie tool. Je schrijft de interacties in markdown en vervolgens kun je er aantrekkelijke plaatjes mee maken in verschillende formaten. Omdat het markdown is, is het relatief makkelijk te onderhouden.
Tenslotte
Documentatie zal altijd wel een lastig onderwerp blijven. Maar met de juiste aanpak en tooling is de benodigde inspanning te overzien. En als je ooit hebt moeten werken aan een serieus stuk code van een ander dan zul je zeker begrijpen dat code zonder documentatie knap vervelend is.