• Dokumentation kostet wertvolle Zeit, die für das Programmieren verloren geht.
• Die Dokumentation muss auf dem Laufenden gehalten werden → kostet noch mehr Zeit und ist eine nervende Arbeit.
• Dokumentationswälder sind schwierig zu verwalten.
• Wenn wichtige Informationen nur in der Dokumentation stehen und nicht im Code, werden sie leicht übersehen.
• Schreibe Code, der nicht dokumentiert werden muss!
• Programmiersprachen sind das Kommunikationsmedium der Entwickler → sprechenden Code schreiben.

nach \cite[S. 58ff.]{Goodliffe2006}

• Code wird (deutlich) häufiger gelesen als geschrieben, also schreibe verständlichen Code und kommentiere sinnvoll!
  • 
  • (via http://osteele.com/archives/2008/01/programmers-pyramid)
• Schreibe nur Kommentare, wenn es keine bessere Möglichkeit gibt, den Code verständlicher zu machen!
• Kommentare sind absolut unnütz (und sind evtl. falsch und veralten schnell), wenn sie lediglich den Code wiederholen.
• Gute Kommentare erklären das Warum anstatt das Wie!
• Vermeide magische Zahlen und Werte → nutze sprechende Konstanten!
• Wichtiger Code muss hervorstechen und unwichtiger vor dem Leser "versteckt" werden.
• ASCII-Art vermeiden (sieht bei anderer Tab-Konfiguration absolut unsinnig aus)
• Tipps für sinnvolle Kommentare
  • unerwartete, überraschende Codeteile (Workarounds etc.) dokumentieren
  • die Wahrheit sagen (= Code und Kommentar konsistent halten)
  • keine Witzchen oder Wortspiele einbauen
  • so exakt wie möglich ausdrücken
  • die Gegenwart beschreiben und keine geänderten Codeteile dokumentieren → dafür ist die Versionsverwaltung zuständig
  • verständliche Sprache und korrekte Rechtschreibung und Grammatik verwenden