Regel 

Funktionen ohne erläuternden Kommentaren.
Funktionen ohne Kommentaren sind schwer zu 
zu für andere Entwickler.

Unterstützte Sprachen: 45+

Einleitung

Funktionen ohne Kommentare zwingen Entwickelnde, die Absicht allein aus Implementierungsdetails abzuleiten. Dies verlangsamt Code-Reviews und macht die Wartung fehleranfälliger. Fehlende Erklärungen verbergen auch Annahmen bezüglich Validierung, Eingabeerwartungen oder Sicherheitsbeschränkungen. Eine klare Dokumentation reduziert Missbrauch und hilft Teams, das Code-Verhalten schneller zu verstehen.

Warum es wichtig ist

Auswirkungen auf die Sicherheit: Fehlende Kommentare verbergen Annahmen bezüglich Validierung, Autorisierungsprüfungen und vertrauenswürdigen Eingaben, wodurch Missbrauch erleichtert und Sicherheitsrisiken erhöht werden.

Leistungsauswirkungen: Undokumentierte Funktionen können falsch verwendet werden, was zu wiederholten teuren Operationen, unnötigem Parsing oder ineffizienter Datenverarbeitung führt.

Wartbarkeit: Entwickelnde verbringen mehr Zeit mit dem Lesen und Reverse Engineering von Logik, wenn die Absicht nicht dokumentiert ist, was Refactoring und Onboarding verlangsamt.

Code-Beispiele

❌ Nicht konform:

// No explanation of expected input or security assumptions
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Warum es falsch ist: Die Funktion verarbeitet sicherheitsrelevante Felder, dokumentiert aber keine Annahmen über vertrauenswürdige Quellen, erwartete Struktur oder Eingabebeschränkungen.

✅ Konform:

/**
 * Normalize user data from external input.
 * Expects: `user` contains `id`, `email`, and `roles`.
 * Rejects invalid structures and filters unsafe role values.
 * Ensures normalized identifiers and lowercased email for consistency.
 */
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Warum das wichtig ist: Der Kommentar dokumentiert Absicht, erwartete Eingaben und Sicherheitsbeschränkungen, was die Nutzung vorhersehbar macht und unsichere Integration verhindert.

Fazit

Fügen Sie jeder Funktion klare Kommentare hinzu, bei der Absicht, Annahmen oder Einschränkungen nicht offensichtlich aus der Signatur hervorgehen. Dokumentieren Sie, was die Funktion erwartet, was sie zurückgibt und jegliches sicherheitsrelevantes Verhalten. Dies verbessert die Überprüfungsqualität, reduziert Missbrauch und gewährleistet ein vorhersehbares Verhalten in der gesamten Codebasis.