Inhaltsverzeichnis
06. Dokumentation (extern)
- Themen
- Warum ist Dokumentation wichtig?
- Vorurteile gegenüber Dokumentation
- Arten von Dokumentation
- Probleme mit (externer) Dokumentation
- Folien
Zentrale Aspekte
- Grundlegende Ideen und Konzepte lassen sich schwer
durch den Quellcode selbst dokumentieren. - Dokumentiert werden sollte das „Was“ und „Warum“ (bzw. was warum nicht).
Das „Wie“ beantwortet der Quellcode. - Eine minimale externe Dokumentation (readme, install, erste Schritte)
ist für größere Projekte unumgänglich. - Externe Dokumentation lässt sich nur mit viel Disziplin
mit dem Quellcode synchron halten. - Einfach nutzbare Dokumentationswerkzeuge helfen,
Dokumentation und Quellcode synchron zu halten.
Weiterführende Literatur/Links
Eine kommentierte und handverlesene Liste mit weiterführender Literatur zum Thema. Die Auswahl ist zwangsläufig subjektiv.
Dokumentation im wissenschaftlichen Kontext
Die in der Vorlesung präsentierte Einteilung der Dokumentation im wissenschaftlichen Kontext, u.a. mit den theoretischen Abhandlungen (wie Abschlussarbeiten und Veröffentlichungen) stammt aus [Scopatz, 2015Scopatz, Anthony; Huff, Kathryn D. (2015): Effective Computation in Physics, O'Reilly, Sebastopol] (dort Kapitel 19). Dieses Buch verfolgt an vielen Stellen einen ähnlichen Ansatz wie die Vorlesung.
- Scopatz, Anthony; Huff, Kathryn D. (2015): Effective Computation in Physics, O'Reilly, Sebastopol
Der Quellcode ist das Design
Der Essay „The Source Code Is the Design“ von Jack R. Reeves von 1992 ist im Anhang von Robert C. Martins Buch abgedruckt – und fand wohl erst dadurch eine weite Verbreitung. Das Buch selbst ist ebenfalls sehr lesenswert und behandelt Themen, die später in der Vorlesung noch detaillierter behandelt werden.
Der Artikel erschien ursprünglich unter dem Titel „What Is Software Design?“ im C++ Journal. Er findet sich online zusammen mit zwei weiteren Texten von Reeves bei developer.*:
http://www.developerdotstar.com/mag/articles/reeves_design_main.html
Dort kann man auch ein PDF-Dokument aller drei Essays herunterladen.
- Martin, Robert C. (2003): Agile Software Development. Principles, Patterns, and Practices, Prentice Hall, Upper Saddle River, New Jersey
Illustrationen
Die Serie von Dilbert-Comicstreifen, die in der Vorlesung zu Beginn und am Ende gezeigt werden, um die Wichtigkeit des Themas zu zeigen, finden sich unter folgenden Webadressen: