Benutzer-Werkzeuge

Webseiten-Werkzeuge


se:dokumentation

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!
  • Programmiersprachen sind das Kommunikationsmedium der Entwickler → sprechenden Code schreiben.

Quelltextdokumentation

nach [Goodliffe2006, S. 58ff.]

  • Code wird (deutlich) häufiger gelesen als geschrieben, also schreibe verständlichen Code und kommentiere sinnvoll!
  • 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
se/dokumentation.txt · Zuletzt geändert: 2014-04-05 11:42 (Externe Bearbeitung)