myPerfectCode

Sparen Sie sich Ihren Kommentar

In dem Buch CleanCode von Uncle Bob gibt es eine Stelle, die zusammen gefasst folgendes aussagt:

“Wenn du Code mit Hilfe von Kommentaren erklärst, läuft etwas falsch. Code, der erklärt werden muss, ist schlechter Code. Er kann sich selbst nicht ausdrücken und benötigt seinen Kommentar als Stütze.”

Diese Stelle fand ich besonders interessant, weil sie einen Teil eines Programms nicht als Gütesiegel “Das ist ja gut kommentiert!” ansieht, sondern als Indiz für unsauberen Codes.

So habe ich da vorher nicht gesehen. Jeder sollte in meinen Kommentaren nachlesen können, was ich im Code darunter gebaut habe. Aber es stimmt. Wenn sich Code nicht selbst erklärt, ist er sogenannter “Magic Code”. Jeder macht einen Bogen drum und dankt dem Herrn, wenn es Kommentare gibt, die ein wenig Licht in das Wirrwarr bringen. Dann wird das Wirrwarr mit viel Anstrengung erweitert – bis zum nächsten Wiedersehen. Dann wird die Erweiterung des Wirrwarrs kommentiert, damit man diese Stelle auch wieder warten kann.

Uncle Bob sieht das anders. Er soll kein Kommentar hinzugefügt oder erweitert werden, der Code selber soll sagen, was dort gerade abläuft. Der Programmierer soll sich als Autor verstehen, der mit Hilfe seiner Programmiersprache eine Geschichte erzählt.

Ist eine Geschichte gut strukturiert und zudem flüssig geschrieben, ist sie eingänglich und kann schnell verstanden werden. Zu Geschichten, die sich nicht sofort offenbaren, gibt es in der Literatur passende Interpretationswerke, die manchen Studenten die Klausur gerettet haben. Bei der Literatur ist es Kunst und ist somit ein Wert an sich – unser Code soll aber arbeiten und erhält dadurch seinen Wert. Schlecht lesbarer und somit schlecht wartbarer Code arbeitet am Ende auch schlecht.

Bei einer Diskussion in unserer Firma kam der Einwand, dass dies nicht für alle Kommentare gilt. Daher möchte ich unsere Sicht der Abgrenzung in folgenden Punkten zusammen fassen:

1. Wenn kein Code sichtbar ist, wie z.B. bei APIs, muss die JavaDoc die Funktion, deren Aufruf sowie deren Verarbeitung erklären. Am besten anhand von Beispielen. Dies bezieht sich somit auf public-Funktionen.
2. Klassen sollten im Kopf kurz per JavaDoc erläutert werden. Ist diese Klasse ein Teil einer offenen API umso ausführlicher.
3. Bei Kommentaren im Ablaufcode wird es kritisch. Hier sollte lieber darüber nachgedacht werden, ob es nicht sinnvoller sein könnte, den Code umzuschreiben. Ausnahmen sind Meta-Informationen, die nicht nicht direkt den Ablauf erklären wollen. Diese Kommentare erklären nicht den Ablauf des Codes, sondern bieten Zusatzinformationen an. Beispiel: “NIcht Threadsafe”
4. Private Methoden sind wie Ablaufcode zu werten. Lieber schauen, ob die Funktion mit dem jeweiligen Namen Sinn macht oder sogar komplett aufgeteilt werden sollte.
5. Variablennamen sollten nicht kommentiert werden müssen. Kennen Sie das? Da steht eine Variable counter über die der Kommentar steht /* Zähler */. Das ist redundant und kann gleich gelöscht werden. Bei einem Wort sollte man sich Mühe geben, dass es für sich ausdrucksstark ist.

Diesen Ansatz sehe ich weniger als Dogma, sondern soll ein Indiz liefern, wann entweder Information doppelt vorhanden ist (guter Code und erklärender Kommentar) oder der Code schlecht geschrieben ist und sich ohne Hilfe nicht lesen lässt.

Viel Freude beim Entwickeln!

Autor: Stephan Scharff-Rahn

PS: Gleicher Meinung? Anderer Meinung? Über Eure Meinung würde ich mich sehr freuen.

Quellen: Buch CleanCode (Robert C. Martin) – http://www.amazon.de/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

Link zur Gruppe myPerfectCode: http://www.xing.com/group-66550.040701