Code-Dokumentation – hilfreich oder Zeitverschwendung?
Kommentare

Es ist sicherlich eines der meist-diskutierten Themen unter Programmierern: Soll man Codes kommentieren und dokumentieren oder hält dies nur von den eigentlichen Aufgaben eines Programmierers ab? Klar

Es ist sicherlich eines der meist-diskutierten Themen unter Programmierern: Soll man Codes kommentieren und dokumentieren oder hält dies nur von den eigentlichen Aufgaben eines Programmierers ab? Klar ist, dass die meisten gerne auf die mühsame Detailarbeit verzichten würden – und dafür gibt es Gründe!

Während Joe Kunk vom Visual Studio Magazine vorsichtig abwägt und am Ende einräumen muss, dass die Antwort nicht so einfach ist, legt sich sein Kollege Peter Vogel fest und ruft Programmierer auf, dass es nicht zu spät ist, mit dem Dokumentieren von Codes aufzuhören. Dabei liegen die beiden Autoren – und generell die Pro- und Anti-Kommentierungslager – nicht so weit auseinander, wie es auf den ersten Blick scheint. Jeder, der schon einmal den Code eines anderen Programmierers weiterentwickelt oder auch nur gelesen hat, weiß, wie frustrierend es ist, wenn ein Code schwer zu durchschauen ist. Darum gilt: Ein Code sollte immer eindeutig sein und es sollte aus ihm hervorgehen, was der Code bewirken soll. Daher ist die Frage vielleicht viel weniger, ob man kommentieren soll, sondern eher, wie viel Kommentar nötig ist und ab wann es überflüssige Zeitverschwendung ist.

Sicherlich sind gute Kommentare ein Qualitätsmerkmal und in jedem Fall sollten sie darlegen, was der Zweck des vorliegenden Codes ist. Joe Kunk betont dabei, dass es bei Quellcode extrem schwierig sei, die Funktionsweise und die Intention des Programmierers mit absoluter Sicherheit zu erkennen. Kommentare sollten daher die Intention offen legen und wenn nötig erklären, wie der Algorithmus diese Ziele unterstützt. Weiterhin sei es dabei eine Frage des Respekts gegenüber anderen Programmierern, die sich einmal mit dem fertigen Code auseinandersetzen müssen, dass man strukturiert und eindeutig arbeitet, wobei eine genaue Dokumentation behilflich sein kann. Ebenfalls können so potentielle Probleme aufgezeigt werden, wodurch den Testern die Arbeit erleichtert wird.

Zeitverschwendung oder essentieller Erkenntnisgewinn?

Kritiker bemängeln, dass die Dokumentation lediglich eine überflüssige, zeitaufwändige Arbeit sei, da es keine Auswirkungen auf das fertige Programm habe. Schließlich entfernen Compiler oder Interpreter alle Comment Lines, die nur für den Leser des Codes Relevanz haben. Die Zeit, die ein Programmierer für den Kommentar aufbringt, kostet Geld und Energie und hält so von den eigentlichen Aufgaben ab. Zudem gibt es keine verbindlichen Übereinkünfte bezüglich der Begriffe oder Vorgehensweisen, wodurch die Kommentare subjektiv und mitunter missverständlich sind. 

Um Missverständnissen vorzubeugen, gehen viele Kommentare ins Detail und verkommen so im Extremfall zu einer Art zweiten Version des Codes, wodurch kein weiterer Erkenntnisgewinn folgen kann. Hinzu kommt, dass während der Code weiterentwickelt wird, die Kommentare unbeachtet der Veränderungen gleich bleiben und so ungenau oder gar hinfällig werden, um schließlich  eher in die Irre zu leiten als zum Verständnis beizutragen. Wenn ein Programmierer einen Code mit ausführlichen Kommentaren vorfindet, kann er also nicht sicher sein, ob diese Kommentare verlässlich sind, wodurch diese keinen oder nur geringen Wert besitzen.

Peter Vogel schlägt daher vor, Kommentare und Dokumentationen auf das wirklich Wesentliche zu beschränken – also auf die wichtigen Informationen zur Intention und, nur wenn nötig, zur Herangehensweise. Oberstes Gebot ist es, den Code verständlich zu halten und auf Insider-Formulierungen und umständliche Befehle zu verzichten. Kurz: Real Obvious Code (ROC) statt Write-Only Code (WOC). Auch das bedeutet jedoch einen Mehraufwand, da ein ROC nur in den wenigsten Fällen auf Anhieb gelingt. Wesentlich häufiger weiß man beim Programmieren zwar, was man erreichen möchte, nicht jedoch, wie man an dieses Ziel gelangt. Um aus diesem manchmal verschlängelten Trampelpfad eine leicht zu manövrierende Code-Autobahn zu machen, muss man den Code nochmals durchgehen und umständliche Formulierungen beseitigen. Je besser der Code dabei wird, desto weniger Erklärungen braucht er.  Doch auch dies birgt natürlich Probleme, denn mit jeder Änderungen besteht die Gefahr, Bugs in ein funktionierendes System einzubauen,  ohne dass eine erfolgreiche Änderung dabei die Performance verbessert hätte. Sinn macht ein solches Refactoring daher nur dann, wenn man im Zuge eines Test-Driven Developments (TDD) fehlerhafte Änderungen leicht wieder rückgängig machen kann, ohne hierzu viel Zeit aufbringen zu müssen.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -