Dokumentation
« | 26 Jun 2022 | »Wenn man den Satz
Gute Programmierer sind schlechte Dokumentierer.
umgekehrt auffasst, dann bin ich einer der besten Programmierer, denn Dokus schreiben mag ich so gar nicht.
However … auch das muss mal sein.
Der C-Teil der Kernbibliothek des GATE Frameworks gatecore ist nun zum
Großteil mit doxygen Kommentarblöcken befüllt und somit konnte die
erste sinnvolle Version der Projektdokumentation generiert werden.
Da mein doxygen Setup so aussieht, dass nur dokumentierte Codes abgebildet
sind (und nicht alles automatisch extrahiert wird), musste ich also vor
jeder öffentlichen Funktion entsprechende Kommentare anfügen.
Das ist zwar noch lange nicht vollständig, doch nun sind zumindest viele Kernfunktionen mal “offiziell” geworden.
Dokumentation ist gleichzeitig auch ein Interface-Review und tatsächlich sind mir einige Inkonsistenzen aufgefallen, die ich teils gleich korrigieren konnte. Andere Details stehen auf der “Redesign” Liste.
Damit auch ein bisschen mehr Qualitätsdruck entsteht, wurden die generierten
HTML Dateien auf den Webspace hochgeladen, wo sie unter
http://www.opengate.at/doc einsehbar sind.
Der nächste Punkt wird das C++ Interface werden und parallel verlangen auch
die Bibliotheken gateio, gatesystem, gateencode, gatenet und
gategraphics nach einer Schnittstellenbeschreibung.
Fazit
Leider frisst das Dokumentieren wirklich extrem viel Zeit, denn hier gilt tatsächlich im Header:
Für eine Zeile Code, braucht man 5 Zeilen Dokumentation.
Und wenn dann noch jeder Parameter seine Geheimnisse preisgeben soll, merkt man erst, dass tatsächlich 5 mal mehr Beschreibungszeilen erforderlich sind, als für die eine Codezeile, die eine Funktion ankündigt.
Ich hoffe, dass meine Motivation hinreichend lange aufrecht bleibt, um die Grundzüge des Projektes darzustellen.
Mal sehen, was in einem Jahr daraus werden wird.