Dokumentation

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.

📧 📋 🐘 | 🔔
 

Meine Dokus über:
 
Weitere externe Links zu:
Alle extern verlinkten Webseiten stehen nicht in Zusammenhang mit opengate.at.
Für deren Inhalt wird keine Haftung übernommen.



Wenn sich eine triviale Erkenntnis mit Dummheit in der Interpretation paart, dann gibt es in der Regel Kollateralschäden in der Anwendung.
frei zitiert nach A. Van der Bellen
... also dann paaren wir mal eine komplexe Erkenntnis mit Klugheit in der Interpretation!