Themen

Arten von Dokumentation im Code

Argumente für und gegen Kommentare

Regeln für Kommentare

Werkzeuge zur automatischen Erzeugung

Folien

PDF

• 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.

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, 2008Martin, Robert C. (2008): Clean Code. A Handbook of Agile Software Craftmanship, Prentice Hall, Upper Saddle River, New Jersey]. 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, 1978Kernighan, Brian W.; Plauger, P. J. (1978): The Elements of Programming Style, McGraw-Hill, New York]. Das dortige sechste Kapitel widmet sich dem hier diskutierten Thema. Sehr kurz und teilweise von den gleichen Autoren ist Kapitel 1 in [Kernighan, 1999Kernighan, Brian W.; Pike, Rob (1999): The Practice of Programming, Addison Wesley, Boston]. Gute Hinweise finden sich schließlich auch in [Hunt, 1999Hunt, Andrew; Thomas, David (1999): The Pragmatic Programmer, Addison-Wesley, Boston], Kapitel 8, S. 248ff.

• Hunt, Andrew; Thomas, David (1999): The Pragmatic Programmer, Addison-Wesley, Boston
• Kernighan, Brian W.; Plauger, P. J. (1978): The Elements of Programming Style, McGraw-Hill, New York
• Kernighan, Brian W.; Pike, Rob (1999): The Practice of Programming, Addison Wesley, Boston
• Martin, Robert C. (2008): Clean Code. A Handbook of Agile Software Craftmanship, Prentice Hall, Upper Saddle River, New Jersey