28 Dez

Dokumentation im Code – ja oder nein?

Programmcode wird zwar immer für Maschinen geschrieben, aber wirklich gut ist er erst, wenn ihn auch Menschen ohne Schwierigkeiten lesen können. Doch was heißt „ohne Schwierigkeiten“? Viele Entwickler setzen dazu auf eine mehr oder weniger detaillierte Dokumentation des Codes. Der Gedanke ist klar: Kommentare sollen helfen, den Code besser nachzuvollziehen und Nachfragen oder gar Missverständnisse zu vermeiden. Aber sollte ein guter Code nicht eigentlich selbsterklärend sein? Wir gehen der Frage nach.

Warum Code überhaupt dokumentiert wird

Kommentare zwischen den Codezeilen sind nicht per se schlecht. Sie haben ihre Daseinsberechtigung. Ein Beispiel: Sie möchten komplexe Funktionsabschnitte deklarieren. Oder Sie möchten erwähnen, warum Sie an einer bestimmten Stelle genau diese Parameter verwenden und keine anderen. Problematisch wird es dann, wenn Sie

  • mehr Augenmerk auf die Dokumentation legen als auf den Code selber, und
  • die Funktionalität des Codes statt seiner Intention kommentieren.

Hinter einer übereifrigen Dokumentation steckt oft die Angst, dass andere den Code falsch oder gar nicht verstehen könnten. Denken Sie umgekehrt: Wie lässt sich Code schreiben, damit er keiner weiteren Kommunikation bedarf? Denn dann kommen Sie schnell an den Punkt, an dem Ihnen klar wird, dass 99% aller Kommentare überflüssig sind.

Ein guter Code spricht für sich

Je weniger Sie kommentieren, desto stärker müssen Sie auf klare und strukturierte Anweisungen achten. Clean Code zwingt Sie gewissermaßen ganz von selbst dazu, möglichst simpel und effizient zu coden, weshalb dieses Prinzip in der Softwareentwicklung auch so hochgelobt ist. Versuchen Sie mit Ihren Codezeilen zu kommunizieren, statt sich in ausufernden Dokumentationen zu verlieren. Hier sind vier Gründe, warum Sie zukünftig weniger kommentieren sollten:

1.      Kommentare lenken ab

Ein perfekter Code hat immer einen gewissen Fluss, wenn Sie ihn durchgehen, so als würden Sie einen flüssigen Text lesen. Kommentare unterbrechen diesen Fluss ausnahmslos und erschweren so in vielen Fällen – paradoxerweise – das Verständnis des Codes. Das ist vor allem dann der Fall, wenn es sich um redundante Kommentare handelt, die keine neuen Informationen liefern.

2.      Kommentare kosten Zeit

Zeit ist die kostbarste Ressource in der Softwareentwicklung. Überschlagen Sie einmal in Gedanken, wie viel Zeit Ihnen das Verfassen der Kommentare kostet und wie viel Zeit andere damit verbringen, diese zu lesen und mit dem Code in Einklang zu bringen. Und wer pflegt und aktualisiert die Kommentare, wenn der Code zu einem späteren Zeitpunkt angepasst werden muss? Der Punkt ist: Dokumentieren geht immer zu Lasten der Produktivität. Wenn Sie dauerhaft schneller und effizienter arbeiten wollen, müssen Sie rigoros Kommentare einsparen.

3.      Schlechte Kommentare verwirren Ihre Kollegen

Vielleicht kennen Sie das Szenario selbst: Jemand kommentiert etwas völlig Offensichtliches und Sie fragen sich insgeheim: Warum wird das kommentiert? Steckt noch mehr dahinter? Lässt sich das auch anders interpretieren? Redundante oder irreführende Kommentare können eine ganze Menge Probleme verursachen, die völlig unnötig sind. Vertrauen Sie Ihren Programmierfertigkeiten und denen Ihrer Kollegen. So oder so werden Kommentare Ihren Code nicht besser machen.

4.      Kommentare überlagern die Neutralität des Codes

Programmiersprachen sind neutral, eigene Kommentare nicht. Denken Sie immer daran, dass Ihre Kommentare Teil des Quellcodes sind und von jedem, der damit arbeitet, eingesehen werden können. Besonders relevant ist dieser Punkt für jeden, der dazu neigt, Kommentare auch als eine Art Notizen zu verwenden. Gestern Nacht noch kurz etwas vermerkt, am nächsten Morgen längst vergessen – und Ihr Kollege amüsiert sich prächtig. Darum sollten Sie sich angewöhnen, so wenige Kommentare wie nur möglich zu hinterlassen.

Fazit: Gute Programmierer kommunizieren mit ihrem Code

Schreiben Sie Programmiercode so, dass man ihn auch ohne oder nur mit wenigen Kommentaren verstehen kann. Damit sparen Sie selbst und anderen eine Menge Zeit, arbeiten produktiver und fokussieren sich auf klare, einfache Strukturen. Erfahrungsgemäß lässt dies auch das Vertrauen in die eigenen Fähigkeiten wachsen, weil Sie lernen, ausschließlich mit Ihrem Code zu kommunizieren.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht.