Kommentare, die Informationen liefern, die der Code nicht liefern kann

Ziel

Kommentare, über die eine pflegende Person froh ist: der Grund für eine überraschende Entscheidung, die externe Randbedingung, die sie erzwungen hat, und die Falle, in die sie sonst tappen würde.

Voraussetzungen

Code, dessen Struktur und Namen bereits sagen, was er tut; Kommentare sind kein Ersatz dafür.

Schritte

1. Vor dem Schreiben eines Kommentars fragen, ob ein besserer Name, eine kleinere Funktion oder eine Assertion ihn überflüssig machen würde.
2. Das Warum festhalten: die Geschäftsregel, den Fehler, gegen den dies absichert (mit Ticket- oder Commit-Referenz), den Abschnitt der Spezifikation, der das ungewöhnliche Verhalten verlangt.
3. Randbedingungen und Folgen festhalten: „muss vor X laufen, weil …“, „dieser Wert wird persistiert, eine Änderung erfordert eine Migration“.
4. Vorübergehende Massnahmen mit der Bedingung für ihre Entfernung markieren, nicht nur mit TODO: „entfernen, sobald alle Clients Version ≥ 3 senden (siehe Metrik-Dashboard)“.
5. Den Kommentar nahe am beschriebenen Code halten; ein Kommentar am Dateianfang über eine Zeile in der Mitte veraltet.
6. Im Review einen Kommentar, der den Code wiederholt oder ihm widerspricht, als Mangel behandeln.

Erwartetes Ergebnis

Die Kommentardichte sinkt, während ihr Informationsgehalt steigt; Lesende hören auf, sie zu überspringen.

Grenzen und Prüfbasis

Docstrings öffentlicher APIs folgen eigenen Regeln (sie beschreiben Verträge). Generierter Code und Konfiguration benötigen unter Umständen mehr Erklärung als handgeschriebener Code. Es wird keine Messung behauptet.