Lorem ipsum dolor sit amet

Mijn eerste tijdschriftartikel ooit was voor de allerlaatste editie van PT Embedded Systems. Het ging over het documenteren van softwarearchitecturen, op een manier die gebaseerd was op werk van het Software Engineering Institute (SEI) en IEEE 1471, een richtlijn voor architectuurbeschrijvingen. In die tijd was ik van mening dat softwaredocumentatie belangrijk was, omdat software weliswaar maar één keer wordt gemaakt, maar daarna nog oneindig vaak aangepast. Dan helpt het als je als ontwerper of programmeur de structuur van het softwarebouwwerk kunt nakijken voordat je er de spreekwoordelijke zaag in zet.

Nu zijn er ook mensen, en die waren er toen al, die dat niet nodig vinden. Die zeggen genoeg te hebben aan de code en de informatie die ze daaruit kunnen halen. Dat gaat goed, dat zal ik niet ontkennen, mits de omvang van de code niet te groot is, of het ontwikkelteam (en de hoeveelheid parallelle wijzigingen) klein.

De middenweg is in veel gevallen een combinatie van geschreven ontwerpdocumentatie en informatie gegenereerd uit de code – het heeft niet zo veel zin software-interfaces op al dan niet digitaal papier uit te schrijven als je ze ook al in code beschikbaar hebt. Voorwaarde is dat die code is voorzien van verklarend commentaar, dat dan weer wel. Dit pas ik ook met veel plezier toe in de ontwikkeling van mijn eigen product. Mijn documentatie helpt een viertal ontwikkelaars om te begrijpen wat er in mijn hoofd is ontstaan en hoe zich dat heeft vertaald naar een stuk software dat zij mogen uitbreiden en aanpassen.