Die Kunst des stillen Refactorings: Warum KI-Kommentare, die den Prompt verraten, deiner Codebasis schaden
Der Kommentar, der zu viel verrät
Manche Kommentare tauchen mittlerweile überall auf. Man erkennt sie sofort:
# Jetzt mit Dictionary Comprehension wie besprochen
user_emails = {user.id: user.email for user in users}
# Den besprochenen Bug bei der Null-Behandlung behoben
if data and data.get('value'):
process(data['value'])
Diese Kommentare erklären den Code nicht. Sie protokollieren das Gespräch. Und das ist ein Problem.
Warum „Prompt Leak"-Kommentare Code-Smell sind
Wenn ein Kommentar erklärt, was der Entwickler die KI gebeten hat, statt was der Code macht, entstehen mehrere Probleme:
1. Zeitliche Verwirrung Der Kommentar setzt voraus, dass jemand die Entwicklung mitverfolgt hat. „Jetzt verwenden wir..." impliziert einen Zeugen des vorherigen Zustands. Zukünftige Maintainer – inklusive Du-in-zwei-Jahren – haben diesen Kontext nicht.
2. Dokumentationsverfall Kommentare, die an den Prompt gebunden sind, werden obsolet, sobald sich Anforderungen ändern. Wenn sich Requirements weiterentwickeln, führen diese Kommentare Leser aktiv in die Irre.
3. Rauschen statt Signal Gute Kommentare erklären warum, nicht was. Der Code zeigt bereits, was er tut. Kommentare sollten Absicht, Constraints und Kontext beleuchten, die aus der Implementierung nicht offensichtlich sind.
Der Test: Würde ein Martian es verstehen?
Ein einfacher Check: Könnte jemand ohne Kenntnis deines Entwicklungsprozesses diesen Kommentar verstehen?
Schlechter Kommentar:
# Von for-Schleife auf List Comprehension für Effizienz geändert
results = [transform(x) for x in data]
Guter Kommentar:
# List Comprehension performt bei großen Datasets besser dank Interpreter-Optimierung
results = [transform(x) for x in data]
Die gute Version erklärt warum dieser Ansatz gewählt wurde – und bleibt wertvoll, lange nachdem der Code geschrieben wurde.
Was Vibe Code wirklich braucht
VIBe Coding – KI-gestützte Entwicklung, die Speed über Perfektion stellt – hat durchaus seinen Wert. Geschwindigkeit zählt. Aber Velocity sollte nicht auf Kosten der Wartbarkeit gehen.
Wenn dein KI-Assistent einen Kommentar vorschlägt, frag dich:
- Erklärt er warum dieser Code existiert?
- Würde er in zwei Jahren noch Sinn ergeben?
- Dokumentiert er den Zweck des Codes oder den Entwicklungsprozess?
Falls Letzteres der Fall ist: löschen. Dein zukünftiges Ich wird es dir danken.
Bessere KI-Kollaborationsgewohnheiten aufbauen
Die Lösung ist nicht, KI-Assistenten zu meiden – sondern bessere Review-Gewohnheiten zu entwickeln:
Kommentare lesen, bevor man sie akzeptiert. Bringt der Kommentar echten Mehrwert oder protokolliert er nur den Chat-Verlauf?
KI-generierte Kommentare umschreiben. Besser noch: eigene schreiben. Du verstehst den Business-Kontext, den die KI nicht kennt.
Team-Standards etablieren. Wenn solche Kommentare durch Code Reviews rutschen, wird die Codebase-Qualität schleichend erodieren.
Selbstdokumentierenden Code nutzen. Klare Benennung, gute Struktur und passende Abstraktionen machen Kommentare oft komplett überflüssig.
Fazit
Code wird viel häufiger gelesen als geschrieben. Kommentare, die den Prompt statt den Zweck dokumentieren, erzeugen Technical Debt, die mit der Zeit wächst. Im Stress des Shippens ist es verlockend, das durchgehen zu lassen – aber es ist eine Form von Technical Debt, die aktiv in die Irre führt.
Die besten Codebases erzählen eine Geschichte. Kommentare sollten die Handlung erklären, nicht die Notizen des Autors.
Bei NameOcean glauben wir, dass großartige Entwicklungspraktiken über Hosting hinausgehen. Ob du gerade dein MVP vibe-codest oder Enterprise-Systeme architektonisch gestaltest – die Fundamentals sauberen, wartbaren Codes bleiben essentiell. Deine Domain ist deine digitale Identität – stell sicher, dass der Code dahinter einen guten Eindruck macht.