Boehrsi.de - Blog

Dokumentationen sind wichtig und man sollte sie vor allem in professionellen Projekten mit größeren Teams sehr gut pflegen. Diesen oder einen ähnlichen Satz hört man als Entwickler häufiger und das mit Recht. Denn wie soll jemand neues Wissen wie ein Tool funktioniert oder wie man einen Release Build der App anstößt ohne etwas Dokumentation.
Also auch wenn Dokumentationen schreiben vielleicht nicht die dankbarste Aufgabe ist, in diesem Bereich der Softwareentwicklung ist ein gewisses Bewusstsein für derartige Dinge vorhanden.
Doch wie sieht es mit privaten Projekten aus, die man nebenbei baut und vielleicht als Prototyp liegen lässt? Hier gibt es meistens keine Dokumentation, keine weiteren Hilfen oder ähnliches. Dabei ist es egal ob das kleine Projekt ein Prototyp bleibt oder ob etwas aktiv Genutztes draus wird.

Das ist ein Problem, welches einem früher oder später das Leben schwer machen wird. So zuletzt vor wenigen Tagen bei mir geschehen. Ich habe eine kleine Futter App geschrieben, welche aus einer Reihe von JSON Dateien die Statistik und damit auch die Top 10 meines Blogs auslesen kann. Damit letzteres mit nur einem Klick eine schöne Ausgabe generiert, gibt es einen Abgleich zwischen URLs und den erstellten Beiträgen. Auf diese Weise kann ich direkt die Titel mit auslesen und spare mir manuelle Arbeit. Damit dieser Abgleich funktioniert und ich eine schöne Markdown Liste generieren kann, ist eine weitere JSON Datei von Nöten. Diese wird automatisch beim Update meines Blogs erstellt und muss lediglich ins Projekt kopiert werden.
Klingt einfach und schnell gemacht, aber halt nur wenn man weiß was man tut. Ich hatte das letzte Mal vor einigen Monaten besagten Flow durchgeführt und Überraschung, ich vergaß den zweiten Schritt. Statt also binnen Sekunden fertig zu sein, beschäftigte ich mich mit Debugging. Denn es gab eine nichtssagende Exception und ich dachte es sei ein Coding Problem. Eine Zeile Dokumentation hätte mich vor 30 Minuten lustigem Suchen bewahren können.
Insofern mein Rat, investiert die 60 Sekunden und schreibt ein paar Worte zu Abläufen und auch zum Code. Ihr werdet es euch bei der nächsten Nutzung des Tools / Projekts / Codes danken. Ich bevorzuge hier neben In-Code-Dokumentation eine einfache Markdown Readme Datei. Selbige wird in den meisten Git Web-Tools direkt schön angezeigt, sodass man auch eine gute lesbare Doku hat.