Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
Nächste Überarbeitung | Vorhergehende Überarbeitung Nächste Überarbeitung Beide Seiten der Revision | ||
se:dokumentation [2009-01-30 14:13] stefan angelegt |
se:dokumentation [2009-02-14 21:44] stefan |
||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
- | ====== (Code-)Dokumentation ====== | + | ====== Dokumentation ====== |
* Dokumentation kostet wertvolle Zeit, die für das Programmieren verloren geht. | * 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. | * Die Dokumentation muss auf dem Laufenden gehalten werden -> kostet noch mehr Zeit und ist eine nervende Arbeit. | ||
Zeile 6: | Zeile 6: | ||
* **Schreibe Code, der nicht dokumentiert werden muss!** | * **Schreibe Code, der nicht dokumentiert werden muss!** | ||
* Programmier**sprachen** sind das Kommunikationsmedium der Entwickler -> sprechenden Code schreiben. | * Programmier**sprachen** sind das Kommunikationsmedium der Entwickler -> sprechenden Code schreiben. | ||
+ | |||
+ | ===== Quelltextdokumentation ===== | ||
+ | **nach {[quellen:Goodliffe2008|S. 58ff.]}** | ||
+ | * 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 | ||
+ |