Elke programmeur is ook schrijver. Althans de echte programmeur, niet de 'klick-and-go' hobbyist. Een echte programmeur schrijft, bij voorkeur pagina's vol code. Het schrijven van documentatie is echter minder populair. Maar dat laatste kunnen we oplossen ...
Programmeurs houden over het algemeen niet van documenteren; ze schrijven liever code. En bij onduidelijkheden kijken ze liever in de code, dan in een document. Dit verschijnsel is al oud; waarschijnlijk even oud als het programmeren zelf. Ik ken geen onderzoek naar dit verschijnsel. Maar het ligt niet aan het schrijven zelf lijkt mij, want dat doen programmeurs frequent. Noch aan een afkeer van boeken, want die lezen ze veel. Wellicht komt het doordat er een andere filesoort of editor gebruikt moet worden. Maar dan is er goed nieuws: Doxygen! Dit is een tool om documentatie te genereren, uit sourcefiles!
Doxygen gaat uit van de code. Het kan de meest gebruikte talen, zoals C, C++, C# en zelfs Objective-C en IDL lezen en analyseren. Hierdoor worden alle functies, objecten en andere structuren automatisch opgenomen in de documentatie. Natuurlijk is er meer nodig voor goede documentatie, namelijk tekst. Beschrijvende tekst die uitlegt wat functies doen en waarom keuzes gemaakt zijn. Als de programmeur die teksten plaats in commentaar, dan zal Doxygen die gebruiken. Waarbij een 'tag' gebruikt wordt om het soort beschrijving aan te geven. Het resultaat kan een goed leesbaar boek worden (kies als formaat: MS-Word of postscript) en/of een stel handige hypertekst-pagina's (keuze uit html of hyper-pdf). Maar ook andere formaten, zoals LaTeX of manual/help-pagina’s zijn mogelijk.
Het excuus "de documentatie is verouderd" om in de code te kijken, is bij gebruik van Doxygen niet meer geldig. Er wordt immers uitgegaan van dezelfde bron(code). Hierdoor is het heel eenvoudig om de documentatie actueel te houden: Het genereren van de documentatie is te automatiseren, bijvoorbeeld in de Makefile. Samen met versiebeheer, maakt dit principe het zelfs mogelijk om correcte documentatie te gebruiken voor elke release.
Om Doxygen te gebruiken, moet je een uitgebreide configuratiefile schrijven. Dat kan afschrikwekkend werken, maar met een beetje google'n valt het reuze mee. En als één programmeur er mee start, kunnen de anderen volgen. Het echte werk is toch het documenteren zelf. Want al gebruiken we die fijne editor, al schrijven we (slechts) codefiles en genereren we de documentatie, het schrijven van zinvol commentaar blijft schrijfwerk. Maar goed, we zijn 'schrijvers'. Althans, de 'tikkers' onder ons.
Elke ingenieur gebruikt tools en iedereen heeft zijn eigen voorkeur; vaak gebaseerd op wat er toevallig als eerste beschikbaar was. Zo ook de ICT-ingenieur. Ook hij gebruikt tools, software-tools wel te verstaan. Daar zijn er oneindig veel van, waardoor kiezen erg moeilijk is.
Het leren gebruiken van een tool a kost tijd. Maar als je de naam en het doel van het tool kent, loont het gebruik al vaak de moeite. Het inleren en inzetten kost vaak minder tijd dan aanmodderen zonder een goed tool.
Veel handige tools worden echter niet gebruikt, eenvoudigweg omdat ze niet bekend zijn. Daarom wenden we deze rubriek aan om degelijke handige tools voor te stellen.
Mail me, voor meer info:
albert
Doxygen is een opensource tool van Nederlandse komaf. Het is ontwikkeld in Eindhoven, door een student aan de TUE. En hoewel de URL www.doxygen.org bestaat, kom je automatisch uit op de site van de ‘computerhobbyclub’ van die universiteit uit.
Er zijn nog veel meer documentatie–generatoren in omloop. In de jaren 90 was het een populair tool om te maken. Sommige ondersteunen slechts één taal; denk aan JavaDoc. Het voordeel van Doxygen is dat het heel compleet is doordat steeds meer goede ideeën uit andere tools er in opgenomen zijn. Daardoor gaan steeds minder mensen een nieuw tool maken; ze breiden liever Doxygen uit.
Voor meer info, kijk op: http://www.stack.nl/~dimitri/doxygen/
De orginele publicatie is beschikbaar in pdf:
