Regel

Kommentar zu das Ziel (warum), nicht die Mechanik (was).
Kommentare das einfach wiederholen was der Code tut 
bietet keine zusätzlichen Wert und kann veralten veraltet.

Unterstützte Sprachen: 45+

Einleitung

Kommentare, die wiederholen, was der Code tut, bieten keine zusätzliche Klarheit und geraten oft aus dem Takt mit der Implementierung. Wenn Kommentare vom Code abweichen, stiften sie Verwirrung und verlangsamen Reviews. Nützliche Kommentare erklären Absicht, Annahmen und die Begründung für Entscheidungen. Dies erleichtert das Verständnis und die Wartung komplexer Logik.

Warum es wichtig ist

Sicherheitsimplikationen: Absichtsbasierte Kommentare legen Annahmen bezüglich Validierung, Eingabevertrauen oder Zugriffskontrolle offen, die in der Implementierung möglicherweise nicht sichtbar sind.

Leistungsauswirkungen: Kommentare, die leistungsbezogene Entscheidungen erläutern, helfen, versehentliche Optimierungen oder Änderungen zu vermeiden, die die erwarteten Leistungsmerkmale beeinträchtigen.

Code-Wartbarkeit: Absichtsbezogene Kommentare helfen Entwickelnde zu verstehen, warum ein Code-Abschnitt existiert, wodurch der Zeitaufwand für Änderungen oder Audits reduziert wird.

Angriffsfläche: Klare Kommentare verringern die Wahrscheinlichkeit, interne Funktionen auf eine Weise zu missbrauchen, die unsicheres Verhalten einführt oder die Angriffsfläche erweitert.

Code-Beispiele

❌ Nicht konform:

// Loop through users
for (const user of users) {
    // Convert email to lowercase
    user.email = user.email.toLowerCase();
}

Warum es falsch ist: Diese Kommentare wiederholen, was der Code bereits zeigt, und liefern keinen Kontext zu Absicht oder Einschränkungen.

✅ Konform:

/**
 * Normalize user emails so downstream permission checks
 * compare consistent lowercase values. Required because
 * external systems may send mixed-case emails.
 */
for (const user of users) {
    user.email = user.email.toLowerCase();
}

Warum das wichtig ist: Der Kommentar erklärt, warum Normalisierung erforderlich ist, wodurch die Absicht geklärt und falsches Refactoring verhindert wird.

Fazit

Schreiben Sie Kommentare, die erklären, warum der Code notwendig ist, nicht, was jede Zeile bereits zeigt. Beschreiben Sie Annahmen, Einschränkungen und Begründungen, wenn diese nicht offensichtlich aus der Implementierung hervorgehen. Dies schafft wartbare Dokumentation, die auch bei der Weiterentwicklung des Codes nützlich bleibt.