Dokumentation: Wie kommentiere ich richtig?

6. Oktober 2013 · Kategorien: PHP, Webentwicklung

Richtig Kommentieren

Richtig kommentieren ist für viele Entwickler ein leidiges Thema. Gerne werden Dokumentationen gänzlich vermisst, oder sie erfüllen nicht ihren Zweck.

Generell kann man Kommentare in zwei Arten unterteilen: Kommentare, die der Dokumentation dienen und Codebestandteile wie Funktionen, Klassen und Variablen näher beschreiben. Sowie Kommentare, die den Code selbst beschreiben. Das sind diejenigen Kommentare, die  man in den Funktionen findet.

Kommentare Dokumentation

Die Frage, die wir uns in erster Linie beim Erstellen dieser Kommentare stellen sollten, ist: Was macht der Code?

Angenommen, wir haben eine Datenbank-Tabelle colors. In dieser Tabelle sind ID und Name verschiedener Farben gespeichert.
In unserem Code gibt es eine Funktion namens getColor($n). Diese erwartet das Argument $n, welches die $n-te Farbe aus der Datenbank ausliest und zurückgibt. Die Funktion könnte nun folgendermaßen kommentiert werden:

/**
* Returns the $n-th color
*
* @param int number of the color
* @return string color
*/
public function getColor($n) { ... }

Im Anbetracht der Syntax ist das schon einmal sauber kommentiert: Das Kommentar beginnt mit einem Slash und zwei Sternen, sodass Programme zur automatisierten Erstellung einer Dokumentation (z.B. phpDoc) dieses finden und richtig interpretieren wird.
Dem fremden Programmierer, dem die genaue Funktionsweise unbekannt ist, könnten sich allerdings  Fragen aufstellen, zum Beispiel:
- Was ist überhaupt die $n-te Position? Sind die Farben sortiert?
- Beginnt die Zählweise mit 0 oder 1?
Das heißt, man sollte immer versuchen, sich in andere Programmierer hineinzuversetzen und versuchen, gegebenenfalls auftretende Fragen direkt zu beantworten. Eine bessere Kommentierung könnte so aussehen:

/**
* Returns the $n-th color of all colors ordered by the date they were inserted
*
* @param int $n number of the color, starts with 0.
* @return string color
*/
public function getColor($n) { ... }

Schon besser, oder?

Kommentare inline

Bei dieser Art von Kommentaren sollten wir uns nicht nur die Frage stellen, was wir tun, sondern auch warum.
Folgender Kommentar ist ein Klassiker:

// form was submitted
if($_POST) { ... }

Da wirklich jedem Programmierer verständlich ist, dass das $_POST-Array nur dann gefüllt sein kann, wenn ein Formular abgesendet wurde, ist dieser Kommentar fehl am Platze. Zu viele nicht aussagekräftige Kommentare sind nicht nur überflüssig, sondern können die Lesbarkeit des Codes beeinträchtigen.

Gehen wir zurück zu unserem Beispiel. Angenommen, unsere Applikation fragt den Benutzer nach drei Farben, die er der Reihe nach angibt. Daraufhin sollen ihm drei Grafiken von Kissenbezügen angezeigt werden. Jeder Kissenbezug hat eine der jeweiligen Farben. Nehmen wir an (= Lüge), Studien hätten ergeben, dass Kunden bei Eingabe von Farben in ein Webformular erst als letztes die Farbe angeben, die ihnen am ehesten gefällt. Das ist der Grund, warum im Beispiel der Kissenbezug mit der zuletzt eingegebenen Farbe größer dargestellt werden soll.

Der Code könnte nun so aussehen:

// get third color
$bigPillowCaseColor = getColor(3);

Der Kommentar ist hier wieder kaum hilfreich: Dass die dritte Farbe ausgelesen wird, ist dem fremden Programmierer bereits bewusst. Immerhin ist das schon in der Dokumentation der getColor()-Funktion erklärt. Der Code selbst ist dem Programmierer begreiflich, er könnte sich allerdings fragen, warum nun genau die dritte Farbe ausgelesen wird. Schlimmer noch, er könnte annehmen, dass es sich um einen Fehler handelt, da ihm die erste Farbe in diesem Fall logischer erscheint.

In diesem Fall ist es also ratsam, dem Nutzer kurz und bündig zu erklären, warum wir etwas tun:

// get third color because researchs have shown it's most likely customers favorite color
$bigPillowCaseColor = getColor(3);

In großen Open-Source-Projekten, an denen viele Leute mitarbeiten, nehmen Kommentare oft beträchtliche Zeilen Code in Anspruch.
Das dient dem Codeverständnis fremder Programmierer.

Und immer daran denken: Dieser “fremde Programmierer” könntest auch Du selbst sein, wenn du nach einigen Monaten oder Jahren zurück in Deinen Code schaust.

Autor: | Kategorien: PHP, Webentwicklung

Keine Kommentare zu Dokumentation: Wie kommentiere ich richtig?

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *