====== Dokumentation ======
  * 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!**
  * Programmier**sprachen** sind das Kommunikationsmedium der Entwickler -> sprechenden Code schreiben.

===== Quelltextdokumentation =====
**nach \cite[S. 58ff.]{Goodliffe2006}**
  * Code wird (deutlich) häufiger gelesen als geschrieben, also schreibe verständlichen Code und kommentiere sinnvoll!
    * {{:se:programmers-pyramid.png|}}
    * (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