Code-Kommentare sinnvoll mit KI generieren

1. Was einen guten Code-Kommentar ausmacht

Ein guter Code-Kommentar fügt Wissen hinzu, das sich nicht allein aus dem Lesen des Codes erschließt. Der Code selbst beantwortet bereits die Frage, was passiert, sofern er halbwegs lesbar geschrieben ist: eine Schleife iteriert über ein Array, eine Bedingung prüft einen Status, eine Funktion gibt einen Wert zurück. Ein Kommentar, der genau das noch einmal in Worten wiederholt, liefert keinen zusätzlichen Wert, sondern nur zusätzlichen Text zum Lesen und Pflegen. Die eigentliche Aufgabe eines Kommentars ist es, die Lücke zu schließen, die der Code allein nicht füllen kann: warum diese Lösung, warum diese Reihenfolge, warum diese scheinbar unnötige Sonderbehandlung.

Ein einfacher Test hilft bei der Einordnung: Würde ein erfahrener Entwickler beim Lesen des Codes allein auf diese Information kommen? Wenn ja, ist der Kommentar redundant und kann ohne Informationsverlust entfernt werden. Wenn nein, weil die Information nur aus einem Ticket, einem Bugreport einer Fremdbibliothek oder einer Geschäftsregel stammt, die im Code selbst nicht sichtbar ist, dann ist der Kommentar wertvoll. Mit KI-Werkzeugen wie Claude lässt sich Kommentierung heute in Sekunden über ganze Dateien hinweg erzeugen, was die Frage nach dieser Unterscheidung dringlicher macht als je zuvor.

2. Das Grundproblem: KI kommentiert das Offensichtliche

Wer ein Sprachmodell mit einer generischen Anweisung wie „Kommentiere diese Datei" beauftragt, erhält in der Praxis regelmäßig Kommentare wie // Loop through the items über einer foreach-Schleife oder // Return the result über einer return-Anweisung. Dieses Verhalten ist kein Ausreißer, sondern der statistisch wahrscheinlichste Output bei einer unpräzisen Anweisung, und es tritt bei praktisch allen aktuellen Coding-Assistenten auf, nicht nur bei einem bestimmten Modell. Der Effekt betrifft besonders automatisierte Kommentierungsdurchläufe über größere Dateimengen, bei denen niemand jede einzelne Zeile im Detail prüft.

Der praktische Schaden ist real, auch wenn er selten sofort auffällt. Redundante Kommentare erhöhen die visuelle Dichte des Codes, ohne Informationsgehalt zu liefern, und sie müssen bei jeder Änderung mitgepflegt werden, obwohl sie nichts beitragen, das nicht ohnehin im Code steht. Schlimmer noch: Teams verwechseln hohe Kommentardichte mit guter Dokumentation. Ein Dateibaum voller // increment counter-Zeilen wirkt gepflegt, verdeckt aber genau die Stellen, an denen tatsächlich eine Begründung fehlen würde, etwa bei einem unerwarteten Timeout-Wert oder einer ungewöhnlichen Fehlerbehandlung.

3. Warum Sprachmodelle zu redundanten Kommentaren neigen

Die Ursache liegt im Trainingssignal und in der fehlenden Information, nicht in einem Defekt des Modells. Ein Großteil des öffentlich verfügbaren, kommentierten Codes in Trainingsdaten stammt aus Tutorials, Lehrmaterial und Boilerplate-Generatoren, wo genau diese Art von erklärenden, aber redundanten Kommentaren üblich ist, weil sie Anfängern beim Lesen helfen sollen. Ohne eine explizite gegenteilige Anweisung produziert das Modell also statistisch das, was es am häufigsten gesehen hat: eine Paraphrase der folgenden Zeile.

Hinzu kommt ein strukturelles Problem: Das Modell kennt die eigentliche Begründung für eine Design-Entscheidung oft schlicht nicht, weil sie nirgends im übergebenen Kontext steht. Warum eine Bestandsprüfung erst nach einem bestimmten Event ausgeführt wird, warum ein Retry auf genau drei Versuche begrenzt ist oder warum eine Exception bewusst verschluckt wird, lässt sich nicht aus dem Quellcode allein ableiten. Fehlt dem Modell der Zugriff auf Commit-Historie, Ticket-Referenzen oder Pull-Request-Diskussionen, bleibt ihm nur die Wahl zwischen einer Paraphrase des Codes oder einer erfundenen, plausibel klingenden Begründung, die im schlimmsten Fall schlicht falsch ist.

4. WAS vs. WARUM: der entscheidende Unterschied

Die Unterscheidung zwischen WAS-Kommentaren und WARUM-Kommentaren ist der zentrale Hebel für bessere KI-generierte Dokumentation. Ein WAS-Kommentar beschreibt die Mechanik einer Codezeile und ist fast immer redundant, weil der Code diese Information selbst trägt. Ein WARUM-Kommentar beschreibt eine Entscheidung, eine Randbedingung oder einen Kompromiss, der außerhalb des Codes liegt: eine Geschäftsregel, ein Bug in einer Fremdbibliothek, eine Performance-Abwägung oder eine gesetzliche Vorgabe. Nur die zweite Kategorie rechtfertigt in den meisten Fällen einen Kommentar.

Ein Beispiel verdeutlicht den Unterschied direkt: // increment counter über $counter++; ist ein reiner WAS-Kommentar ohne Mehrwert. // Der Produkt-Repository-Cache von Magento schlüsselt nach SKU, ein Refresh hier vermeidet veraltete Preise nach dem Import ist ein WARUM-Kommentar, der eine Information liefert, die aus dem Code allein nicht ersichtlich wäre. Wer KI-Werkzeuge für Kommentare einsetzt, sollte genau diese Unterscheidung als Filter definieren, statt sich auf die generische Standardausgabe zu verlassen.

5. Gezieltes Prompting für versteckte Constraints

Die Qualität KI-generierter Kommentare hängt fast vollständig von der Präzision der Anweisung ab. Statt „Kommentiere diese Datei" liefert eine gezielte Anweisung wie „Kommentiere ausschließlich Stellen, an denen die Begründung nicht aus dem Code selbst hervorgeht: versteckte Constraints, Workarounds für Bugs in Fremdcode, Reihenfolge-Abhängigkeiten und Performance-Kompromisse. Überspringe alles, was den Code lediglich in Worten wiederholt" deutlich fokussiertere Ergebnisse. Few-Shot-Beispiele im Prompt, die einen schlechten und einen guten Kommentar nebeneinanderstellen, kalibrieren das Modell zusätzlich auf den gewünschten Stil.

Entscheidend ist außerdem, dem Modell überhaupt Zugriff auf die Information zu geben, die einen WARUM-Kommentar erst möglich macht. Ein Verweis auf die zugehörige Ticket-Nummer, ein eingefügter Ausschnitt aus der Commit-Message oder der Kontext einer Pull-Request-Diskussion liefern dem Modell die Fakten, die im Quellcode selbst fehlen. Ohne diesen zusätzlichen Kontext kann selbst die beste Anweisung nur verhindern, dass das Modell Unsinn erfindet, aber sie kann fehlendes Wissen nicht ersetzen.

#!/usr/bin/env bash
# Claude Code: targeted prompt for meaningful comments instead of a generic pass
claude "Review StockReservationService.php and add comments only where the
reasoning is non-obvious from the code itself: hidden constraints, ordering
dependencies, workarounds for third-party bugs, and performance trade-offs.
Do not add a comment that merely restates the following line in words.
Reference the linked ticket MAGE-4821 for the ordering constraint context."

# Good calibration examples inside the same prompt:
# BAD:  // increment counter
# GOOD: // Retry capped at 3: vendor API rate-limits after the 4th call, see MAGE-4821

Dasselbe Prinzip lässt sich über die Anthropic API strukturiert als System-Prompt hinterlegen, sodass jeder Aufruf gegen eine Datei dieselbe Kommentierungsrichtlinie erhält, statt sie in jedem Chat neu zu formulieren. Der folgende Ausschnitt zeigt einen solchen System-Prompt mit expliziten Few-Shot-Beispielen für schlechte und gute Kommentare.

{
  "model": "claude-sonnet-4-5",
  "system": [
    {
      "type": "text",
      "text": "You add PHP comments. Only comment non-obvious reasoning: hidden constraints, ordering dependencies, workarounds for third-party bugs, and performance trade-offs. Never add a comment that restates the following line. Example BAD: '// increment counter' above $counter++. Example GOOD: '// Retry capped at 3, vendor API rate-limits after the 4th call, see MAGE-4821'.",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Add comments to StockReservationService.php following the policy above. Ticket context: MAGE-4821 describes a stock indexer timing issue."
    }
  ]
}

6. Praxisbeispiel: Vorher-Nachher-Vergleich

Ein konkretes Beispiel aus einem Magento-Kontext macht den Qualitätsunterschied greifbar. Eine Funktion prüft den verfügbaren Lagerbestand, nachdem ein bestimmtes Event ausgelöst wurde. Auf den ersten Blick wirkt die Reihenfolge willkürlich, sie ist aber notwendig, weil der zuständige Indexer den Bestandswert erst nach diesem Event aktualisiert. Wird die Prüfung vorher ausgeführt, liefert sie einen veralteten Wert, ohne dass ein Fehler sichtbar wird. Genau diese Information geht bei einer naiven KI-Kommentierung typischerweise verloren.

Der folgende Vergleich zeigt beide Varianten nebeneinander: Die naive Version beschreibt lediglich, was jede Zeile tut, und verliert dabei die kritische Randbedingung. Die gezielt geprompte Version erklärt die Reihenfolge-Abhängigkeit, verweist auf die Ursache im Indexer-Verhalten und macht damit sichtbar, warum ein Refactoring an dieser Stelle riskant wäre, ohne den Indexer-Ablauf zu berücksichtigen.

# --- BEFORE: naive AI comments, restates the obvious, loses the real reason ---
- public function checkAvailability(int $productId): bool
- {
-     // Dispatch the stock update event
-     $this->eventManager->dispatch('stock_item_updated', ['id' => $productId]);
-
-     // Get the stock item
-     $stockItem = $this->stockRegistry->getStockItem($productId);
-
-     // Return whether it is in stock
-     return $stockItem->getIsInStock();
- }

# --- AFTER: comments capture the non-obvious ordering constraint ---
+ public function checkAvailability(int $productId): bool
+ {
+     // The stock indexer only refreshes qty after this event fires.
+     // Reading getStockItem() before dispatch returns a stale value
+     // without raising an error. Do not reorder these two calls.
+     // See MAGE-4821 for the indexer timing investigation.
+     $this->eventManager->dispatch('stock_item_updated', ['id' => $productId]);
+
+     $stockItem = $this->stockRegistry->getStockItem($productId);
+
+     return $stockItem->getIsInStock();
+ }

7. Workarounds und technische Schulden dokumentieren

Workarounds für Bugs in Fremdcode, temporäre Patches und bewusst unschöne Lösungen sind der Bereich, in dem WARUM-Kommentare den größten Nutzen stiften, weil ihr Fehlen später am teuersten wird. Ohne Begründung sieht ein sleep(2) vor einem API-Call wie ein Zufallsartefakt aus, das beim nächsten Refactoring kommentarlos entfernt wird, obwohl es einen bekannten Race-Condition-Bug in einer Drittanbieter-API abfängt. Ein gutes Prompting-Muster bittet das Modell gezielt, ungewöhnliche Konstrukte wie Magic Numbers, verschluckte Exceptions, feste Wartezeiten oder auffällige Retry-Logik zu identifizieren und für jede Fundstelle einen strukturierten Kommentar vorzuschlagen.

Ein bewährtes Format für solche Kommentare besteht aus drei Teilen: der Begründung, seit wann der Workaround existiert, und der Bedingung, unter der er entfernt werden darf, etwa „TODO: entfernen, sobald Vendor-Ticket #4821 gefixt ist". Wichtig ist die Grenze der KI-Unterstützung an dieser Stelle: Das Modell kann das Muster erkennen und die Struktur vorschlagen, aber die tatsächliche Begründung muss aus einer verlässlichen Quelle stammen, etwa aus Commit-Historie oder Ticket-System. Erfindet das Modell die Begründung selbst, weil der Kontext fehlt, entsteht ein Kommentar, der schlimmer ist als keiner: einer, der falsches Vertrauen erzeugt.

Bevor überhaupt ein Kommentar formuliert wird, hilft eine einfache Heuristik, verdächtige Stellen im Code automatisiert zu markieren, damit ein Entwickler gezielt die fehlende Begründung nachträgt, statt die gesamte Datei manuell zu durchsuchen.

// Heuristic scan: flag suspicious constructs that likely need a WHY comment
const fs = require('fs');

const SUSPICIOUS_PATTERNS = [
  { regex: /sleep\(\s*\d+/i, label: 'fixed sleep/delay' },
  { regex: /catch\s*\([^)]*\)\s*\{\s*\}/i, label: 'swallowed exception' },
  { regex: /retry|maxAttempts|MAX_RETRIES/i, label: 'retry logic' },
  { regex: /\b\d{3,}\b/, label: 'magic number' },
];

function findUncommentedSuspects(filePath) {
  const lines = fs.readFileSync(filePath, 'utf8').split('\n');
  const suspects = [];

  lines.forEach((line, i) => {
    const prevLine = lines[i - 1] || '';
    const hasComment = prevLine.trim().startsWith('//');

    for (const { regex, label } of SUSPICIOUS_PATTERNS) {
      if (regex.test(line) && !hasComment) {
        suspects.push({ line: i + 1, label, code: line.trim() });
      }
    }
  });

  return suspects;
}

console.log(findUncommentedSuspects('app/code/Mironsoft/SeoSuite/Model/ImportRetryHandler.php'));

8. Kommentarqualität im Code-Review prüfen

Claude Code lässt sich gezielt als zusätzlicher Review-Durchlauf einsetzen, der nicht die Korrektheit des Codes prüft, sondern ausschließlich die Kommentarqualität eines Diffs bewertet. Ein solcher Durchlauf klassifiziert jeden neuen oder geänderten Kommentar als WAS-Kommentar, der zur Streichung markiert wird, oder als WARUM-Kommentar, der erhalten bleibt. Zusätzlich kann derselbe Durchlauf auf Codestellen hinweisen, die einen Kommentar verdient hätten, aber keinen erhalten haben, etwa eine ungewöhnliche Regex, einen deaktivierten Linter-Hinweis oder eine Sonderbehandlung für einen Edge Case.

Diese Praxis lässt sich in einer CLAUDE.md-Konvention oder als wiederholbarer Prompt festhalten, sodass jedes Teammitglied denselben Maßstab anlegt, statt Kommentarqualität dem individuellen Geschmack zu überlassen. Der Aufwand für diesen zusätzlichen Review-Schritt ist gering im Vergleich zum Nutzen, weil er verhindert, dass sich redundante Kommentare unbemerkt über Monate im Repository ansammeln und die eigentlich wichtigen WARUM-Kommentare darin untergehen.

# Claude Code review pass: classify comments in a diff as redundant or valuable
import anthropic

client = anthropic.Anthropic()

with open("diff.patch") as f:
    diff_content = f.read()

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=(
        "You review PHP diffs for comment quality only, not correctness. "
        "For every added or changed comment, classify it as WHAT (restates "
        "the following line, flag for removal) or WHY (explains a hidden "
        "constraint, workaround, or trade-off, keep it). Also flag lines "
        "with unusual constructs (magic numbers, swallowed exceptions, "
        "fixed sleeps) that have no comment at all."
    ),
    messages=[{"role": "user", "content": diff_content}],
)

print(response.content[0].text)

9. Typische Fehler und Grenzen im Vergleich

Über die grundlegende WAS-gegen-WARUM-Unterscheidung hinaus tauchen bei der KI-gestützten Kommentierung wiederkehrende Fehlermuster auf. Übermäßige Kommentierung jeder einzelnen Zeile ist das häufigste, dicht gefolgt von generischen Phrasen wie „Verbessertes Fehlerhandling", die keine konkrete Information tragen. Ein subtileres Risiko ist die erfundene, aber plausibel klingende Begründung: Fehlt dem Modell der echte Kontext, füllt es die Lücke gelegentlich mit einer Erklärung, die überzeugend formuliert, aber schlicht falsch ist. Das ist gefährlicher als ein redundanter Kommentar, weil es aktiv in die Irre führt.

Keines dieser Muster lässt sich vollständig automatisieren, weil das eigentliche WARUM-Wissen oft außerhalb des Codes liegt, in Köpfen, Tickets und Commit-Historien. Die realistische Grenze KI-gestützter Kommentierung ist deshalb nicht die Textqualität, sondern der Zugriff auf Kontext: Ein Modell mit Zugriff auf Ticket-System und Git-Historie liefert spürbar bessere Kommentare als eines, das nur die isolierte Datei sieht.

10. Zusammenfassung

KI-generierte Code-Kommentare lösen ein reales Problem, bergen aber ein ebenso reales Risiko: Ohne gezielte Anweisung produzieren Sprachmodelle bevorzugt WAS-Kommentare, die den Code lediglich in Worten wiederholen, statt WARUM-Kommentare, die verborgene Constraints, Workarounds und Design-Entscheidungen erklären. Die Ursache liegt im Trainingssignal und im fehlenden Zugriff auf Kontext, der nicht im Quellcode selbst steht. Der einfache Test „Würde ein erfahrener Entwickler das ohnehin sehen?" trennt beide Kategorien zuverlässig.

Gezieltes Prompting mit expliziten Anweisungen, Few-Shot-Beispielen und ergänzendem Kontext aus Tickets oder Commit-Historie verbessert die Trefferquote deutlich, ersetzt aber nicht die Notwendigkeit, echte Begründungen aus verlässlichen Quellen bereitzustellen. Ein zusätzlicher Review-Durchlauf, der gezielt auf WARUM-Gehalt prüft, verhindert, dass redundante KI-Kommentare unbemerkt ins Repository gelangen und dort die eigentlich wichtigen Informationen überdecken.

11. FAQ: Code-Kommentare sinnvoll mit KI generieren