15. Dokumentation im Code

Themen: Arten von Dokumentation im Code; Argumente für und gegen Kommentare; Regeln für Kommentare; Werkzeuge zur automatischen Erzeugung
Folien: PDF

Zentrale Aspekte

Dokumentation im Code sollte auf das
notwendige Minimum beschränkt werden.
Veraltete Dokumentation schadet mehr als sie nützt.
Formulierungen sollten so knapp und präzise wie möglich,
die Formatierung konsistent und übersichtlich sein.
Unklarer Code sollte nicht dokumentiert,
sondern umgeschrieben werden.
Dokumentationswerkzeuge erleichtern die Arbeit,
setzen aber konsistente Formatierung voraus.

Weiterführende Literatur

Eine kommentierte und handverlesene Liste mit weiterführender Literatur zum Thema. Die Auswahl ist zwangsläufig subjektiv.

Robert Martin widmet in seinem Buch „Clean Code“ ein ganzes Kapitel (Kapitel 4) dem Thema {[martin-rc-2008]}. Viele der Grundlagen sind allerdings wesentlich älter. Ein in mancher Hinsicht zeitloser Klassiker, der leider (momentan) nur antiquarisch erhältlich ist, ist „The Elements of Programming Style“ von Kernighan und Plaugher {[kernighan-bw-1978]}. Das dortige sechste Kapitel widmet sich dem hier diskutierten Thema. Sehr kurz und teilweise von den gleichen Autoren ist Kapitel 1 in {[kernighan-bw-1999]}. Gute Hinweise finden sich schließlich auch in {[hunt-a-1999]}, Kapitel 8, S. 248ff.