Kommentare haben eine Eigenschaft, die kein anderer Teil des Codes hat: Der Compiler prüft sie nicht. Nichts hindert einen Kommentar daran, falsch zu sein — und mit jeder Änderung am Code darunter steigt die Wahrscheinlichkeit, dass er es wird.
Ein falscher Kommentar ist schlimmer als keiner. Er wird geglaubt.
// Prüft, ob der Kunde volljährig ist (18 Jahre)
private static bool Pruefe(Kunde k)
{
return k.Alter >= 16; // vor zwei Jahren geändert, Kommentar blieb
}Wer hat recht?
Der Leser weiss es nicht. Ist die Grenze falsch implementiert, oder ist der Kommentar veraltet? Beides ist plausibel — also muss er die Fachabteilung fragen. Ohne Kommentar hätte er nur eine Zahl gesehen und hätte sie geglaubt.
Die Grundregel
Erkläre nicht, was der Code tut. Sorge dafür, dass der Code es selbst sagt.
Der überwiegende Teil der Kommentare, die man im Alltag findet, ist der Versuch, eine schlechte Benennung oder eine zu lange Methode zu entschuldigen. Und dieser Versuch lässt sich fast immer in eine Refaktorisierung übersetzen.
Der Kommentar wird zum Namen
Kommentiert
// Prüft, ob die Bestellung
// versandfertig ist
if (b.Bezahlt
&& b.Positionen.Count > 0
&& b.Adresse != null
&& !b.IstStorniert)
{
Versende(b);
}Benannt
if (IstVersandfertig(b))
{
Versende(b);
}
private static bool IstVersandfertig(
Bestellung b) =>
b.Bezahlt
&& b.Positionen.Count > 0
&& b.Adresse != null
&& !b.IstStorniert;Der Kommentar ist nicht verschwunden — er ist zum Methodennamen geworden. Und dieser Name veraltet nicht unbemerkt, weil er direkt über der Bedingung steht, die er beschreibt.
Die üblichen Verdächtigen
Der Kommentar, der die Zeile wiederholt. Er kostet eine Zeile und liefert nichts:
// Erhöht den Zähler um eins
zaehler++;
// Der Konstruktor
public Kunde() { }
/// <summary>
/// Holt oder setzt den Namen.
/// </summary>
public string Name { get; set; }Der Abschnittskommentar — er markiert Blöcke innerhalb einer zu langen Methode:
public void Verarbeite(Auftrag auftrag)
{
// ---- Validierung ----
…
// ---- Berechnung ----
…
// ---- Speichern ----
…
}Diese Kommentare sind eine Landkarte
Sie zeigen dir genau, wo die Methode zerfällt. Drei Abschnitte sind drei Methoden — Validiere, Berechne, Speichere — und danach braucht keiner der drei noch eine Überschrift.
Der Changelog im Dateikopf. Er stammt aus einer Zeit vor der Versionsverwaltung:
// -----------------------------------------------
// 2019-03-14 M. Keller Erstellt
// 2020-11-02 A. Weber Mehrwertsteuer 7.7 -> 8.1
// 2021-06-30 M. Keller Bugfix Rundung
// -----------------------------------------------git log und git blame wissen das alles — vollständig, korrekt und ohne dass jemand daran denken muss. Der Block im Kopf weiss es lückenhaft und veraltet.
Auskommentierter Code. Der hartnäckigste Fall:
var betrag = BerechneNetto(bestellung);
// var betrag = BerechneNetto(bestellung) * 1.081m;
// betrag = Math.Round(betrag, 2);
// TODO: prüfen, ob die alte Variante wieder gebraucht wirdWarum das besonders teuer ist
Niemand traut sich, solchen Code zu löschen — er könnte ja wichtig sein. Also bleibt er, und mit jedem Jahr wird er unverständlicher, weil der Kontext fehlt, in dem er einmal Sinn ergab. Git vergisst nichts. Lösch ihn.