Die Antwort auf
alle Fragen in der Softwareentwicklung: "It depends" bzw. "kommt drauf an".
Zu Dokumentation hat fast jeder eine Meinung. Und je nachdem, wen man fragt wird man *sehr* unterschiedliche Antworten erhalten. Fakt ist: Eine pauschale Antwort gibt es nicht.
Demnach musst du die Frage für dich beantworten. Dabei solltest du folgendes bedenken:
- Wer soll die Doku lesen? Und was erwarten diese? Doku ist mit Sicherheit falsch, wenn sie an den Anforderungen der Stakeholder vorbei geht. Und das kann je nach Projekt sehr unterschiedlich sein.
- Doku ist kein Selbstzweck. Je mehr du davon hast, desto aufwendiger ist es, sie zu pflegen. Und veraltete Doku ist i.d.R. schlechter als gar keine.
- Je näher die Doku am Code ist (rein räumlich gesehen), desto wahrscheinlicher ist, dass sie gepflegt wird. Selbsterklärender Code > Kommentare im Code > Doku mitversioniert im selben Repository > Doku außerhalb des Repos > Doku auf Paper.
- Doku, die keine neue Info hat, ist kontraproduktiv. Doku zu dem Konstruktor, die sagt "Create erzeugt ein neues Objekt" oder noch besser "Konstruktor der Klasse" ist sinnloses Gebabbel und sollte man unterlassen.
- Je mehr Stakeholder du hast, desto mehr Doku ist nötig. Schreibst du ne
API für hunderte anderer Entwickler, brauchst du mehr Doku, als wenn du der einzige bist, der das unter die Finger kriegt. Wenn sich das Entwicklerteam ständig ändert, brauchst du mehr Doku, als wenn du ein festes, unveränderliches Team hast.
- Je mehr sich der Code ändert, desto schneller veraltet Doku und desto weniger solltest du haben. Abstrakte Basisklassen musst du eher beschreiben als temporäre Implementierungen, die beim nächsten Refactoring eh wieder wegfallen. Ebenso ist es sinnvoller, die grobe Architektur zu dokumentieren (weil die sich nur langsam ändert), als irgendwelche privaten Methoden, die eh ständig umgeschrieben werden. Dokumentiere Abstraktes und Allgemeines eher als konkretes.
- Doku macht nur Sinn, wenn sie auch gelesen wird. Wenn sie zu detalliert ist und niemand den Detailgrad braucht, ist das vergeudete Zeit. Diagramme sind gut. Denn damit kann man Zusammenhänge übersichtlich zeigen, die man im Code nie sehen würde, weil man im Code quasi immer mit der Lupe vor nem monumentalen Wandteppich steht. Diagramme, die aber nicht übersichtlich sind, sind wertlos.
- Wenn du wissen willst, was gute Doku ist, guck dir schlechte an.
- Besser noch: frag die Stakeholder, die die Doku lesen sollen nach Beispielen für gute und schlechte Doku. Frag sie, was sioe ganz konkret brauchen und erwarten. Frag sie, was sie haben wollen und wie sie die Doku benutzen würden. Ganz konkret die Personen, die das betrifft. Wir hier können nur Anhaltspunkte liefern und ggf. aus dem Nähkästchen plaudern. Aber wir können hier keine Abschließende Antwort liefern, weil wir dein Projekt nicht kennen.
- ...
mfg
Christian