“Code is like humor. When you have to explain it, it’s bad.”
Cory House
Um kein Thema wird in der Softwareentwicklung so vehement und radikal gestritten, wie die Source Code Dokumentation.
Streitpunkte gibt es dabei viele. Soll überhaupt dokumentiert werden und wenn ja was? Alle Methoden einer Klasse oder nur öffentliche Schnittstellen, vielleicht nur die Klasse oder nur die API einer Bibliothek? Sollte komplizierter Code innerhalb einer Methode dokumentiert werden oder ist der funktionsfähige Code gar nicht für fremde Augen bestimmt?
Unter dem Begriff der Source Code Dokumentation mischen sich Dokumentationen für sehr unterschiedliche Nutzer.
Grundsätzlich sollte die Dokumentation für die Nutzer und die Entwickler unterschieden werden. Als Nutzer der Software sind hier die Softwareentwickler gemeint, die eine Software in Form einer Bibliothek verwenden. Diese Entwickler benötigen eine API Dokumentation mit Beschreibungen von Klassen, Interfaces und öffentlichen Methoden. Zusätzlich ist eine Dokumentation der grundlegenden Konzepte der Software und ihrer Verwendung nötig.
Streit entbrennt in der Regel darüber, was der Entwickler der Software an weiterer Dokumentation in seinem Code benötigt.
Das obige Zitat von Cory House bringt auf humorvolle Weise ein grundlegendes These auf den Punkt. Schlechter Code wird durch Dokumentation nicht besser.
Häufig passiert es sogar, dass die einmal erstellte Dokumentation nicht angepasst wird und mit der Zeit keinerlei Nutzen mehr hat. Statt zu helfen verwirrt die Dokumentation und sorgt schlimmstenfalls sogar für Fehler.
Ein Konferenzsprecher spottete vor Jahre darüber, dass die hilfsreichste Einstellung moderner Entwicklungsumgebungen wäre, Kommentare in der Hintergrundfarbe darzustellen.
Der Zwang zur Dokumentation sorgt häufig auch zu Stilblüten, die dem Entwickler die Arbeit schwer machen. Der Bildschirm erlaubt nur eine Zahl von etwa 30 Zeilen auf dem Bildschirm. Ärgerlich dann, wenn etwa die Hälfte durch sinnlose Inlinekommentare gefüllt sind. So existierten Sourcen, in dem jede Methode mit der Kommentarzeile
// Vorbedingung prüfen
beginnen und mit der Zeile
// Rückgabewert
enden. Kommentare die ein noch immer existierendes, grundlegendes Übel in der Software Branche zeigen. Führungsetagen ohne jedwede Ahnung von den notwendigen Kenntnissen in der Softwareentwicklung, erstellen Vorgaben ohne Realitätsbezug und praktischen Nutzen.
Wir stellen uns einmal eine Werkstatt vor, in dem auf jedem Werkzeug hilfreiche Beschriftungen wie Zange oder Hammer stehen. Wer einen Hammer nicht kennt, hat in der Werkstatt nicht zu hantieren und wer einen Konstruktor nicht kennt, sollte keinen Sourcecode verändern. Grotesk wurde es, als manche Entwickler diese Kommentare auch in Void Methoden ohne Parameter einfügten.
Eine weitere Unart sind Inlinekommentare, die innerhalb einer Methode erklären, was der nachfolge Code so bewirkt. Martin Fowler erklärt in seinem Buch Refactoring, was mit diesem Kommentar anzustellen ist. Es ist der Name einer neuen Methode, die man aus der alten Methode herauszuschneidenen hat. Völlig unverständlich, warum so etwas heutzutage noch vorkommt. Alle Entwicklungsumgebungen unterstützen das Methode-Extrahieren als Refactoring Grundfunktion.
Wenn jemand nicht weiter weiß, keine Zeit erübrigen kann oder innerlich schon gekündigt hat, dann verwendet er Task Tags wie TODO, FIXME oder DONOTCHANGE in seinen Kommentaren. Diese Tags erscheinen im ersten Augenblick sehr nützlich, kann man doch weiter arbeiten, ohne durch ein Randproblem aufgehalten zu werden. Wer aber 15 Jahre alte TODO Tags findet, erinnert sich an die folgende Regel.
“Später heißt niemals!”
Anonymous
Sourcecode benötigt grundsätzlich wenig Dokumentation, weil er eine funktionale Beschreibung eines Algorithmus ist. Egal wie schlecht geschrieben, bewirkt der Algorithmus etwas und dazugehörige Unit Test beschreiben Wirkungsweise und Randbedingungen. Nutzt der Entwickler SOLID Prinzipien und Design Pattern, verständliche Namen für Klassen, Methoden und Parametern, hält sich an akzeptierte Grundsätze, dann kann der geschulte Leser einen Sourcecode so einfach lesen wie einen Comic.
Ganz ohne Dokumentation wird man vermutlich niemals auskommen. Daher noch ein schönes und versöhnliches Zitat zum Thema Dokumentation am Ende dieses Beitrags.
“Documentation is a love letter that you write to your future self.”
Damian Conway