Es ist wahrscheinlich der tausendste Artikel eines Programmierer Blogs übers Kommentieren. Nicht wird so oft angeprangert und trotzdem scheint es nicht besser zu werden. Jetzt kippe ich mein Fett auch noch ins Feuer und hoffe das Beste ;)
Was sollte man beim Kommentieren unbedingt beachten? Wann ist ein Kommentar gut, wann verbesserungswürdig und wann überflüssig?
- In den Kopfbereich jeder Datei gehört ein Kommentar, damit man weiß, was der Zweck dieser Datei ist.
- Vor jede Klassendefinition sollte man einen Kommentar anbringen, der den Zweck der Klasse beschreibt. Wenn eine Datei eine einzige Klassendefinition beinhaltet, kann man Punkt 1 vergessen :)
- Das gleiche gilt für Funktionen. Kurz den Zweck der Funktion beschreiben, dann die Parameter und eventuell mögliche Werte listen.
- Dito für Membervariablen.
- Inline-Kommentare (direkt im Funktionscode) sollten nicht erklären, was passiert, sondern warum. Wenn man beschreiben muss, was man gerade macht, ist der Code selbst nicht aussagekräftig.
- Inline-Kommentare sollten auf der Höhe des Codes stehen. Wenn es eine super kurze Codezeile ist, dann gerne auch danach.
- Kommentare müssen immer im sichtbaren Bereich des Editors bleiben, damit man sie beim durchscrollen nicht übersieht.
- Bei mehrzeiligen Kommentaren darauf achten, dass jede neue Kommentarzeile auf der gleichen Höhe beginnt.
- Entweder für die Kommentare ein definiertes Format im Sinne von JavaDoc bzw. phpDocumentor verwenden oder einen eigenen Guide entwickeln, der lückenlos dokumentiert ist.
- In den Kommentaren im Kopfbereich weitgreifende Änderungen im Sinne eines Changelogs festhalten. Hierzu Datum, Änderung und Name des Autors nennen. Unwichtige Änderungen gehören hier nicht rein, die müssen in einem externen Trackingsystem notiert werden.
- Wenn Änderungen im Quellcode stattfinden - auf jeden Fall überprüfen, ob die Kommentare noch passen. Besonders gerne werden dann die Kommentare im Kopfbereich vergessen!
Ich möchte nochmal auf Punkt 5 eingehen. Der Code selbst sollte schon lesbar sein. Muss man beschreiben, WAS man gerade mit einer Zeile bezweckt, läuft etwas schief.
Ein kleines Beispiel zur Freude meiner Kollegen und ein Rätsel für alle anderen Mitleser: Was passiert hier?
$cum->login($u, $p, $userdao);
Keine Ahnung? Einen blassen Schimmer? Natürlich ist das arg stilisiert. Aber so soll es in der freien Wildbahn öfter vorkommen ;) Jetzt nochmal selbst beschreibend:
$user->login($username, $password);
Jetzt besser? Das DAO hat an dieser Stelle nix zu suchen. Und cum bitte nicht mit einschlägigen Bildern dokumentieren, gemeint war hier: CommunityUserManagement ;) Ich denke wir sind uns alle einig, das man an solch einer Zeile nichts kommentieren muss.
Eventuell ist es gut, bei einer Funktion oder Klasse den Einsatz näher zu beschreiben:
- Wann wird die Funktion aufgerufen?
- Wann sollte ich diese Klasse verwenden?
- Wann auf gar keinen Fall? (Wenn es Alternativen gibt)
Wenn eine Funktion eine Ausgabe macht und direkt etwas herausschickt sollte man das auf jeden Fall in einem Kommentar erwähnen, sofern es nicht schon aus dem Funktionsbezeichner hervorgeht.
