Dokumentation im Code – Pro und Contra
Wie wichtig ist das Dokumentieren von Code? “Sehr wichtig natürlich, denn dadurch lässt sich Code leichter verstehen!” – sagen die Einen. “Unwichtig” – antworten die Anderen, “denn sobald sich Softwareentwickler an die Prinzipien von Clean Code halten, ist die separate Dokumentation unnötig.”. Manche argumentieren auch mit einem Mittelweg: “Man sollte das dokumentieren, was nicht vergessen werden darf!”.
Wenn die Meinung so unterschiedlich sind, dann ist es Zeit für ein Pro und Contra zur Dokumentation von Quellcode.
Warum dokumentieren Softwareentwickler nicht gerne Code?
Die Welt des Programmierens könnte so schön sein, wenn Softwareentwickler ihren Code einfach kommentieren würden. Tun sie aber nicht. Zumindest nicht alle, nicht immer oder nicht auf eine einheitliche Weise. Das hat eine Reihe von Gründen:
- Die Dokumentation von Code ist zeitaufwändig. Ein Kommentar kostet Zeit. Mehr Zeit als kein Kommentar. Und diese Zeit fehlt für andere schöne Dinge, wie bspw. Codieren.
- Softwareentwicklung erfolgt oftmals unter Zeitdruck, so dass Kommentare häufig nicht gepflegt werden und in der Folge die Dokumentation nicht zum aktualisierten Code passt.
- Die Dokumentation hat keinen Einfluss auf die Leistung einer Anwendung. Zusätzlich werden Compiler, Interpreter oder Minifier Kommentarzeilen eliminieren.
- In Entwicklungsabteilungen gibt es keine einheitliche Vorgehensweise für die Erstellung und Pflege von Kommentaren. Die Dokumentation liegt im Ermessen des einzelnen Entwicklers und somit wird akzeptiert, wenn derjenige auf die Dokumentation verzichtet.
- Dokumentieren macht keinen Spaß, es ist sogar im gewissen Maße langweilig.
Darüber hinaus gibt es auch eine Reihe von Gründen, die oftmals nicht ausgesprochen werden, obwohl sie genau so klar sind, wie die Argumente, die häufiger genannt werden:
- Softwareentwickler überschätzen sich. Es mangelt vielen Entwicklern bspw. nicht an der Einsicht, Clean Code Werte und Prinzipien umzusetzen, es mangelt ihnen aber den Fähigkeiten. So legen viele ihren Fokus auf die Korrektheit des Codes, negieren gleichzeitig aber dessen Wandelbarkeit. Als Folge sehen sie gar nicht das Bedürfnis zu dokumentieren.
- Softwareentwickler überschätzen sich – Teil 2. Alleine aufgrund der Tatsache, dass Entwickler nicht in der Lage sind, eine zweit- oder drittbeste Lösung zu implementieren, sondern immer glauben, dass sie mit ihren Codezeilen die definierte Aufgabe am besten lösen, können sie oftmals nicht sehen, dass es tatsächlich andere, bessere Wege gibt. Sie sind von ihrer Implementierung überzeugt. Diese ist aus ihrer Sicht klar und absolut logisch. Natürlich muss etwas Logisches nicht dokumentiert werden.
- Softwareentwickler verschätzen sich. Viele Entwickler glauben, dass eine Dokumentation anderen Entwicklern das Leben erleichtern soll. Warum sollten sie dafür Zeit und Mühe investieren? Dabei verschätzen sie sich aber, denn häufig sind sie selbst diejenigen, die in sechs, zehn oder 12 Monaten sich mit der Implementierung auseinandersetzen müssen, dann aber nicht mehr wissen, warum sie was wie realisiert haben.
- Niemand wird gerne durch eine andere Arbeitskraft ersetzt. Vertriebler nicht, Marketing-Fachleute nicht und Softwareentwickler auch nicht. Eine gute Dokumentation erleichtert anderen Entwicklern die Arbeit mit dem Code – warum sollte das ein Softwareentwickler wollen?
Nicht, dass Sie mich falsch verstehen: einige der genannten Gründe sind allzu menschlich und damit auch nicht überraschend.
Warum sollten Softwareentwickler Code dokumentieren?
Tatsächlich gibt es zwei wesentliche Gründe, warum Softwareentwickler Code dokumentieren sollten:
- Das Lesen von Code ist äußerst schwierig. Selbst wenn Softwareentwickler darin geübt sind und mit Hilfe von Zeilennummer schnell zwischen Codestellen hin und her navigieren, die verwendete Syntax zu verstehen ist nicht einfach. Durch die Verwendung von Kommentaren können Entwickler ihre Absicht vermitteln. Die Dokumentation offenbart die Intention des Codes und nicht seine Funktionalität, denn die ergibt sich aus dem Code. Ein Aspekt, der auch bei Code Reviews wichtig ist.
- Die Dokumentation erleichtert allen Beteiligten die Wandelbarkeit (die Anpassung der Software bedingt durch neue Anforderungen) und die kontinuierliche Verbesserung des Codes (die Steigerung der Performance, die Implementierung von Bugfixes etc.). Die Wandelbarkeit von Code ist für Kunden und Anwender praktisch nicht zu überprüfen, da aber die Implementierung neuer Anforderungen Tagesgeschäft in der Softwareentwicklung ist, sollten Entwickler sich ihr eigenes Arbeiten – und auch das anderer Entwickler – erleichtern.1
Es gibt einige weitere Gründe, wie bspw.
- die Deklaration von komplexen Codebereichen,
- der Respekt anderen Entwicklern gegenüber,
- die Sorge vor der Fluktuation von Softwareentwicklern in Verbindung mit dem Verlust an Insiderwissen,
- die Angst vor Fehlern beim Verstehen von Codezeilen,
- oder die Steigerung der Produktionseffizienz2.
In der Summe sind diese Gründe aber eher nachrangig zu bewerten.
Was sollte überhaupt dokumentiert werden?
Tatsächlich ist die Frage “Was sollte überhaupt dokumentiert werden?” von zentraler Bedeutung bei der Betrachtung von Pro und Contra der Programmierdokumentation. In manchen Artikeln über die sogenannte Inline Source Documentation – wie es hipp auf Englisch heißt – wird propagiert, Kommentare in den Quellcode einzufügen, die einzelne Schritte kurz erklären, so dass andere Entwickler ohne aufwändige Analyse leicht nachvollziehen können, warum ein Code-Schnipsel existiert und welche Funktion er hat.3 In andere Worten: Entwickler sollten zur Sicherheit mit Kanonen auf Spatzen schießen.
Tatsächlich ist es sinnvoll – unabhängig davon, ob man auf der Seite von Pro oder der Seite von Contra steht – genau dies nicht zu tun. Kommentare, die beschreiben, wie Code funktioniert und seine Ziele erreicht, sind eigentlich nur eine zweite Version des Codes. Und als zweite Version stimmen sie entweder mit dem Code überein und liefern keinen Mehrwert, oder sie stimmen nicht überein und liefern unvollständige oder gar falsche Informationen.4 Abgesehen davon, dass es praktisch unmöglich – und sicherlich weder effizient noch effektiv – ist, Code exakt und vollständig zu dokumentieren, entwickelt sich dieser weiter. Eine solche Weiterentwicklung müsste sich entsprechend in der Dokumentation des Codes widerspiegeln, und spätestens hier laufen Theorie und Praxis in unterschiedliche Richtungen.
Diese Überlegungen führen uns zurück zur Frage: Was sollte überhaupt dokumentiert werden? Und die Antwort darauf lautet:
- Kommentare sollten das “Warum” des Codes erklären. Die Intention des Entwicklers. Und eventuell den Zweck, den bspw. eine Klasse oder eine Methode erfüllt.
- Zusätzlich könnte ein Kommentar auch erläutern, wie Ein- und Ausgaben einer Methode zusammenhängen, und welche “Nebenwirkungen” (bspw. das Löschen eines Datensatzes) zu erwarten sind.5
Das ist schon alles. Mehr Dokumentation sollte eigentlich nicht nötig sein.
Fazit
Es gibt valide Argumente für und gegen die Dokumentation im Code. Dokumentation kostet Zeit und spart Zeit. Sie kostet den Entwickler Zeit beim Schreiben, sie spart Zeit beim Verstehen des Codes zu einem späteren Zeitpunkt. Auch wenn der Aufwand des Schreibens meist um ein Vielfaches kleiner ist als der Aufwand des Verstehens (insbesondere wenn dieser mit der Anzahl der Entwickler multipliziert wird, die gemeinsam versuchen, die Codezeilen eines anderen Entwicklers zu verstehen), einfach “mehr” Dokumentation zu fordern, ist zu pauschal und bewirkt wenig. Es ist unnötig, mit Worten zu beschreiben, was offensichtlich und bereits eindeutig als Code formuliert wurde.
Hilfreich ist es, erwähnenswerte Aspekte zu dokumentieren, insbesondere die Intention des Entwicklers beim Codieren und Informationen, die nicht direkt aus dem Code abgelesen werden können. Idealerweise ist der Code selbst klar strukturiert, folgt einem logischen Ablauf und ist dabei sowohl effizient als auch effektiv. Und genau in diesem Sinne sollten Kommentare die Lesbarkeit des Codes steigern: in klaren Worten und mit nützlichen, aber nicht redundanten Informationen, effizient und effektiv.
Die Diskussion über die Dokumentation im Code ist nicht neu und vermutlich gibt es nur einen Weg sie dauerhaft zu beenden: Informationen müssen so bereitgestellt werden, dass der implementierte Codes zu jedem beliebigen, späteren Zeitpunkt relativ zügig zu verstehen ist. Das ist das Ziel der Dokumentation. Das ist eine goldene Regel für Softwareentwicklung.6 Und das ist der Grund für Kommentare im Quellcode.
Hinweise:
Wenn Ihnen der Beitrag gefällt oder Sie darüber diskutieren wollen, teilen Sie ihn gerne in Ihrem Netzwerk. Und falls Sie sich für weitere Tipps aus der Praxis interessieren, dann testen Sie gerne unseren wöchentlichen Newsletter mit neuen Beiträgen, Downloads, Empfehlungen und aktuellem Wissen. Vielleicht wird er auch Ihr Lieblings-Newsletter!
[1] Die Clean Code Developer School: Die Anforderungen auf die Füße stellen
[2] Die Produktionseffizienz zielt darauf ab, den gesamten Prozess der Softwareerstellung als Teil eines Application Lifecycle Managements so effizient wie möglich durchzuführen. Je länger eine Software entwickelt wird, je umfangreicher einer Software wird, desto wichtiger wird die Produktionseffizienz. Handelt es sich um Open Source Software ist die Produktionseffizienz ebenfalls von Bedeutung.
[3] DEV-Insider: Dokumentationsarten in der Übersicht
[4] Brian W. Kernighan und P. J. Plauger: The Elements of Programming Style
[5] Visual Studio Magazine: Why You Shouldn’t Comment (oder Document) Code
[6] Eine goldene Regel der Softwareentwicklung besagt: Quellcode sollte so geschrieben werden, wie es sich ein Entwickler von einem anderen Entwickler wünschen würde.
Michael Schenkel hat im t2informatik Blog weitere Beiträge veröffentlicht, u. a.
Michael Schenkel
Leiter Marketing, t2informatik GmbH