Code richtig dokumentieren

Code zu kommentieren ist unbeliebt - so scheint es zumindest. Man könnte annehmen, das Dokumentieren an sich, sei eine unangenehme Arbeit. Es liegt jedoch viel mehr daran, dass meist gar nicht klar ist, was eigentlich erwähnenswert ist. Dem schreibenden Programmierer ist meist alles klar. Also wird vorläufig nicht dokumentiert. Sobald jemand nachfragt, weil etwas unklar ist, wird punktuell nachgebessert.

Andere Entwickler interessieren sich in der Regel eine ganze Weile nicht für "fremden" Code. Erst Wochen oder Monate später, wenn erste Erweiterungen nötig werden, wird der Code zum ersten Mal durch Kollegen gelesen. Bestenfalls erinnert sich der Entwickler noch daran, was das alles eigentlich sollte. Meist ist dann aber eine Einarbeitung in den eigenen Code nötig.

Eine pauschale Forderung nach mehr Dokumentation ist hier wenig hilfreich.

Kommentare sollten nicht redundant sein

Entwicklern ist der eigene Code "klar". Sie wissen nicht, was es da zu kommentieren gibt. Das hat einen guten Grund!

Es ist absolut überflüssig, in langen Worten zu beschreiben, was offensichtlich ist. Es bringt nichts, vor eine for-Schleife zu schreiben, dass hier eine Schleife von 0 bis zur Länge des Arrays minus Eins läuft. Genauso wenig hilfreich ist es, wenn eine Funktion DM_to_EUR(double betrag) einen Kommentar erhält, der noch einmal ausführlich erklärt, dass hier ein Betrag in Deutschen Mark in Euro umgerechnet werde.

Es muss nicht dokumentiert werden, was bereits als Code verständlich ist. Das setzt natürlich voraus, dass der Code auch verständlich geschrieben ist! So sollte vor allem die Namensgebung so gewählt werden, dass Klassen, Methoden und Variablen von anderen Entwicklern intuitiv und natürlich verständlich sind. (Branchenkenntnis darf durchaus vorausgesetzt werden!)

Es ist also nicht sinnvoll zu beschreiben was im Code bereits steht. Ebenso ist es wenig sinnvoll zu beschreiben, wie etwas funktioniert, da auch dies aus dem Code ablesbar ist. (Wenn dem nicht so ist, sollte man zuerst den Code überdenken und erst dann Kommentare schreiben.)

Absicht klären

Wenn im Programmcode nichts kommentiert werden muss, was ohnehin dort steht, dann bleibt die Frage, was denn eigentlich dokumentiert werden sollte?

Die Antwort liegt auf der Hand: Alles, was nicht im Programmcode steht, aber unmittelbar Einfluss darauf hatte, wie der Code ausgefallen ist. Das bedeutet natürlich nicht, dass alle Anforderungen im Code als Kommentare niedergeschrieben werden sollen.

Wie jeder Programmierer weiß, gibt es unterschiedliche Wege, eine Funktionalität umzusetzen. Daher ist es wichtig für Andere zu wissen, wieso ausgerechnet dieser Weg beschritten wurde. Welche Überlegungen sind hineingeflossen?

So kann sich z.B. ein Entwickler dazu entschließen an einer speziellen Stelle einen Cache zu implementieren. Dies beruht auf der Annahme, dass gerade hier in kurzer Zeit hintereinander dieselben Daten mehrfach verwendet werden.

Solche Annahmen, die über die reinen (bereits anderweitig dokumentierten) Anforderungen hinausgehen, sollten im Code an entsprechender Stelle erfasst werden. Ebenso sollten Entscheidungen und Absichten dargelegt werden.

Fazit

Daher hier Empfehlungen für sinnvolle Kommentare:

Was man nicht dokumentieren muss, wenn der Code eine vernünftige Namensgebung hat:

• nicht beschreiben aus was der Code besteht
• nicht beschreiben wie der Code abläuft

Was hingegen auf jeden Fall dokumentiert werden sollte:

• beschreiben, wieso (Grund) der Code so geschrieben wurde
• beschreiben, welche Entscheidungen und Annahmen getroffen wurden