KI verändert, wie Code entsteht, nicht warum Clean Code wichtig ist
Wenn ein Agent den Code schreibt und liest, für wen sind dann Codekommentare gedacht? Menschen und Agenten brauchen sie, wenn der Code eine Regel nicht selbst erklären kann. Bei Webdelo gilt eine einfache Regel: Mit Typen ausdrücken, was sich typisieren lässt. Benennen, was sich benennen lässt. Kommentieren, was sich nicht erschließen lässt.
Ein Coding Agent ist ein KI-Werkzeug, das Dateien liest und Änderungen vorschlägt oder durchführt. Klare Namen, Typen und Kommentare helfen ihm zu verstehen, was bei diesen Änderungen erhalten bleiben muss. Ein komplexes B2B-System kann über Jahre bestehen und gemeinsam von Menschen und Agenten gewartet werden.
Das ist unsere technische Sicht aus der Arbeit an ERP-, CRM- und B2B-Plattformen. Die folgenden Forschungsarbeiten belegen den Wert aussagekräftigen Kontexts. In welcher Reihenfolge wir diesen Kontext im Code verankern, ist Webdelos eigener Praxisansatz.
Compiler und Coding Agent: Gültiger Code ist nicht gleich lesbarer Code
Ein Compiler oder Interpreter folgt den Regeln der Programmiersprache. Ein Coding Agent nutzt zusätzlich Namen, Typen, Kommentare, Tests und den Kontext des Repositorys, um die Absicht zu erschließen. Code kann korrekt ausgeführt werden, obwohl seine Absicht unklar bleibt.
Wenn Sie $availableCredit in $x1 umbenennen, ändert sich die Berechnung nicht. Doch ein Hinweis darauf, was der Wert bedeutet, geht verloren. Der Agent braucht diesen Hinweis, um zu entscheiden, ob eine gewünschte Änderung zur Kreditprüfung oder zur Abrechnungslogik gehört.
Die CodeT5-Studie von 2021 behandelt die von Entwicklern vergebenen Bezeichner als aussagekräftige Signale beim Modelltraining. Die Studie Code braucht Kommentare von 2024 berichtet über Verbesserungen durch Trainingsdaten, die um Kommentare ergänzt wurden. Beide Arbeiten betreffen das Modelltraining. Keine davon begründet daher eine Regel, jede Methode zu kommentieren.
Die öffentlich beschriebenen Abläufe von Claude Code und Codex arbeiten mit Quelldateien und laden bei Bedarf relevanten Kontext nach. Ihre Dokumentation beschreibt keinen vorgeschriebenen Schritt, der alle Kommentare entfernt und Bezeichner umbenennt, bevor das Modell den Code sieht. Das bedeutet aber auch nicht, dass ein Agent für jede Aufgabe das gesamte Repository liest.
Wo Wissen hingehört: Erst Typen, dann Namen, dann Kommentare
Wir hinterlegen Fachwissen dort, wo Werkzeuge es prüfen und Leser es finden können. Fachliche Typen (Domain Types) kommen zuerst, danach sprechende Namen und eine klare Struktur. Kommentare halten die Gründe fest, die sich damit nicht ausdrücken lassen.
Eine Integration von CRM-Systemen kann beispielsweise sowohl Kunden-IDs als auch Abrechnungskonto-IDs verarbeiten. Beide können Ganzzahlen sein, sind aber nicht austauschbar. Getrennte Typen machen diesen Unterschied sichtbar und prüfbar.
Für die Code-Dokumentation nutzen wir diese Reihenfolge:
- Fachliche Typen: bilden Geschäftsbegriffe ab und setzen deren Regeln durch.
- Namen und Struktur: zeigen, was ein Wert oder eine Operation bedeutet.
- Tests und Verträge: prüfen das erwartete Verhalten und die Anforderungen an Schnittstellen.
- Kommentare zum Warum: erklären Entscheidungen, die sich aus dem lokalen Code nicht erschließen lassen.
- Repository-Dokumentation: erklärt Regeln, die mehrere Module betreffen.
PHP: Von primitiven Typen und PHPDoc zu fachlichen Typen
Betrachten Sie diese alternativen Methodendeklarationen einer Abrechnungsschnittstelle. Die erste nutzt native Typen, lässt aber wichtige Fragen offen:
public function settle(
int $accountId,
int $amount,
string $currency,
int $status
): void;Ist der Betrag in Euro oder Cent angegeben? Welche Statuswerte sind erlaubt? Die Typdeklarationen und strikte Typisierung von PHP können diese fachlichen Fragen nicht beantworten. declare(strict_types=1) regelt die implizite Umwandlung skalarer Typen. Es definiert weder das fachliche Modell noch eine vollständige statische Typisierung.
PHPDoc kann die fehlenden Informationen liefern:
/**
* @param int $accountId Settlement account ID, not customer ID.
* @param int $amount Amount in minor units.
* @param string $currency Supported three-letter currency code.
* @param int $status 0 = pending, 1 = approved, 2 = settled.
*/
public function settle(
int $accountId,
int $amount,
string $currency,
int $status
): void;Jetzt hat der Leser Antworten. Diese Beschreibungen allein setzen die Regeln aber nicht durch. Aufrufender Code kann weiterhin eine Kunden-ID übergeben, wo eine Konto-ID erwartet wird.
Die dritte Version gibt diesen Begriffen eigene Typen:
enum SettlementStatus
{
case Pending;
case Approved;
case Settled;
}
// Closed batches must remain unchanged for reconciliation.
public function settle(
SettlementAccountId $account,
Money $amount,
SettlementStatus $status
): void;Money ist ein Wertobjekt (Value Object): Es hält einen Betrag und seine Währung zusammen. Martin Fowlers Money-Muster erklärt diesen Entwurf. SettlementStatus nutzt eine PHP-Enumeration, um eine abgeschlossene Menge von Werten festzulegen.
Diese Deklarationen bilden nur die Schnittstelle. Die Wertobjekte müssen ihre Eingaben validieren. Die Abrechnungsimplementierung muss die Regeln für Abrechnungsstapel und Statusübergänge durchsetzen. Der verbleibende Kommentar erklärt, warum eine dieser Regeln existiert.
Diese Unterscheidung gilt ebenso für Go und Java. Ein int, long oder allgemeiner EntityId kann die Sprachregeln erfüllen und dennoch wenig über die fachliche Bedeutung aussagen.
Wann PHPDoc weiterhin echte Informationen liefert
Wir behalten PHPDoc bei, wenn es etwas vermittelt, das native Typen nicht ausdrücken können. Werkzeuge zur statischen Analyse können auch einige PHPDoc-Annotationen prüfen.
- Alte Schnittstellen mit unvollständigen nativen Typangaben.
- Array-Strukturen, die erforderliche Schlüssel und deren Werte beschreiben.
- Generische Sammlungstypen für die statische Analyse.
- Verträge, Maßeinheiten und Einschränkungen externer APIs.
- Ausnahmen und Seiteneffekte, die aufrufender Code berücksichtigen muss.
@param OrderStatus $status Order status ergänzt bei einem bereits typisierten Parameter keine Information. Unsere Prüffrage ist einfach: Sagt diese Zeile dem Leser etwas, das die Signatur nicht verrät?
Code kommentieren: Das Warum erklären, nicht das Was
Ein nützlicher Kommentar bewahrt Informationen, die sich aus dem benachbarten Code nicht zuverlässig erschließen lassen. Das kann ein geschäftlicher Grund, eine Einschränkung einer Integration oder eine Sicherheitsregel sein. Den Namen der Operation zu wiederholen, liefert keine solche Information.
Diese Backend-Beispiele veranschaulichen den Unterschied. Die nützlichen Varianten erklären eine Entscheidung, die bei späteren Änderungen beachtet werden muss.
// Redundant: update status.
$order->setStatus(OrderStatus::Settled);
// Useful: Only the provider's confirmed callback authorizes settlement.
$order->setStatus(OrderStatus::Settled);Bei der Entwicklung eines Online-Shops muss eine Zahlungsintegration oft zwischen Einheiten umrechnen. Kapseln Sie die Umrechnung in einer benannten Methode. Dokumentieren Sie dann den externen Grund für diese Darstellung.
// Redundant: set amount.
$request->amount = $payment->minorUnits();
// Useful: This provider accepts integer minor units, not decimal amounts.
$request->amount = $payment->minorUnits();In einem Handelssystem bezeichnen unrealisierte Gewinne und Verluste die Wertänderungen noch offener Positionen. Eine Abrechnungsberechnung kann diese bewusst ausschließen.
// Redundant: calculate total.
$exposure = $settledTrades->total();
// Useful: Unrealized P&L is excluded because it has not settled.
$exposure = $settledTrades->total();Ohne diese Erklärung könnte ein Leser eine bewusste Auslassung für einen fehlenden Bestandteil der Berechnung halten.
Der Kommentar, der einen Deadlock verhindert: Ein Go-Beispiel
Ein Mutex ist eine Sperre, die gemeinsam genutzte Daten vor gleichzeitigen Änderungen schützt. In diesem vereinfachten Go-Ausschnitt setzt der Portfoliodienst die Sperre, bevor er updatePosition() aufruft.
func (p *Portfolio) ApplyFill(symbol string, quantity int64) {
p.portfolioMu.Lock()
defer p.portfolioMu.Unlock()
p.updatePosition(symbol, quantity)
}
func (p *Portfolio) updatePosition(symbol string, quantity int64) {
// Do not lock here - caller already holds portfolioMu.
p.positions[symbol] += quantity
}
Ein Agent, der nur die Hilfsmethode betrachtet, könnte eine Sperre zum Schutz der gemeinsam genutzten Map ergänzen. Derselbe Go-Mutex würde den Aufruf beim erneuten Sperrversuch dauerhaft blockieren. Ein zusätzlicher, separater positionMu kann einen Deadlock verursachen, wenn ein anderer Ausführungspfad beide Sperren in umgekehrter Reihenfolge setzt.
Der Kommentar schützt auch neue Entwickler im Team. Wir prüfen trotzdem alle Aufrufstellen und testen das Verhalten bei gleichzeitigen Zugriffen. Ein Kommentar kann nicht erzwingen, wer eine Sperre hält.
Signal und Rauschen: Warum redundante Kommentare den KI-Kontext belasten
Ein Agent hat ein begrenztes Kontextbudget: die Menge an Material, die er gleichzeitig berücksichtigen kann. Wiederholte PHPDoc-Angaben und zeilenweise Beschreibungen verbrauchen dieses Budget, ohne Bedeutung hinzuzufügen. Ein veralteter Kommentar ist gefährlicher, weil er eine widersprüchliche Version der Regeln liefert.
Anthropics Leitfaden zum Context Engineering empfiehlt aussagekräftige Informationen und das gezielte Abrufen relevanter Details bei Bedarf. OpenAIs Artikel zur technischen Umgebung von Agenten beschreibt das Repository als maßgebliche Informationsquelle. Er erklärt auch, warum übergroße Anweisungsdateien hinderlich sind.
Wir setzen diese Empfehlungen praktisch um: Eine Regel steht nah am Code, für den sie gilt. Modulübergreifende Erklärungen stehen in leicht auffindbaren Repository-Dokumenten. Details werden schrittweise zugänglich gemacht. Die ausführlichen Dokumente werden dann geöffnet, wenn die Aufgabe sie erfordert.
Wer $settlementAccount zu $x1 verkürzt, entfernt ein semantisches Signal, also nützliche Bedeutung. Das senkt den Tokenverbrauch nicht automatisch, da Modelle Text unterschiedlich zerlegen. Wir messen Projektergebnisse, statt prozentuale Einsparungen bei Tokens, Kosten oder Fehlern zu versprechen.
Welche Clean Code Prinzipien auch bei Agentic Coding gelten
Die Grundsätze zu Namen und Kommentaren in Robert Martins Clean Code bleiben auch für KI-lesbaren Code nützlich. Namen sollten die Absicht erkennen lassen. Kommentare sollten Gründe oder Warnungen festhalten. Wir wenden diese Ideen gezielt an, statt jede Empfehlung des Buchs als Pflicht zu betrachten.
Das Kapitel über sprechende Namen bietet praktische Regeln für Menschen und Agenten:
- Absicht zeigen: Verwenden Sie
settledExposurestattvalue. - Sinnvolle Unterschiede sichtbar machen: Unterscheiden Sie
customerIdvonsettlementAccountId. - Suchbare Namen verwenden: Geben Sie einem fachlichen Grenzwert einen gut erkennbaren Konstantennamen.
- Gedankliches Übersetzen vermeiden: Leser sollten sich nicht merken müssen, wofür
x1steht. - Ein Wort pro Begriff verwenden: Nennen Sie dieselbe Operation nicht ohne echten Unterschied mal Abrechnung, mal Verrechnung und mal Buchung.
Diese Begriffe sollten auch in der Benutzeroberfläche erscheinen. Bei der Zusammenarbeit mit einer Webdesign Agentur helfen gemeinsame Fachbegriffe, Beschriftungen und Backend-Verhalten aufeinander abzustimmen.
Das Kapitel über Kommentare fordert nicht, auf Kommentare zu verzichten. Kommentare können verwirrenden Code nicht ausgleichen. Erklärungen zur Absicht und Warnungen sind aber wertvoll. Auch selbstdokumentierender Code braucht Unterstützung, wenn der Grund für eine Entscheidung außerhalb der Implementierung liegt.
Sollten AI Coding Agents zum Kommentieren aufgefordert werden?
Ja, aber "Kommentiere jede Methode" ist die falsche Anweisung. Fordern Sie Agenten auf, verborgene Regeln zu dokumentieren und offensichtliche Syntax nicht zu kommentieren. Kurze, eindeutige Projektvorgaben machen diese Erwartung wiederholbar.
Anthropics Best Practices für Claude Code beschreiben CLAUDE.md als Ort für Projektanweisungen. Wir trennen gemeinsame Entwicklungsregeln von modellspezifischen Anpassungen. Letztere behandelt etwa OpenAIs Leitfaden zu Skills und Prompts.
Ein kompakter Anweisungsblock kann unsere Kommentarregeln klar festhalten:
Prefer domain types and meaningful names over explanatory comments.
Comment non-obvious business rules and intentional omissions.
Document architectural rules, lock ownership, and external API quirks.
Explain security and compliance constraints that local code cannot show.
Do not restate signatures or obvious syntax.
Update affected comments with code, and verify rules against tests and docs.Wir prüfen generierte Kommentare als Aussagen über das System. Kann ein Agent nicht feststellen, warum eine Regel existiert, sollte er die Unsicherheit kennzeichnen. Er sollte keine plausibel klingende Erklärung erfinden.
AI First ist nicht Vibe Coding
Bei Webdelo bedeutet AI First, KI unter menschlicher Aufsicht in die Entwicklungsarbeit einzubeziehen. Human in the Loop bedeutet, dass Entwickler folgenreiche Entscheidungen prüfen und für das Ergebnis verantwortlich bleiben. Ein leistungsfähiges Modell kann die Arbeit auch in einer schlecht gestalteten Umgebung beschleunigen.
Ein persönliches KI-Konto ist nützlich, um eine Idee zu erkunden oder einen funktionsfähigen Prototyp zu bauen. Beim Betrieb eines produktiven B2B-Systems kommen Pflichten hinzu, die nach der ersten funktionierenden Version weiterbestehen:
- Ein fachliches Modell und eine Architektur, die künftige Änderungen ermöglichen.
- Tests und Integrationsverträge, die fehlerhaftes Verhalten erkennen.
- Beobachtbarkeit: Protokolle, Metriken und Warnmeldungen, die Fehler sichtbar machen.
- Sicherheitsmaßnahmen und klare Zugriffsgrenzen.
- Menschliche Prüfung und Verantwortung für Freigaben.
Wie Webdelo AI First und Human in the Loop umsetzt
Wir bereiten die Codebasis mit fachlichen Typen, sprechenden Namen, Kommentaren zum Warum und kurzen Repository-Anweisungen vor. Agenten helfen bei klar begrenzten Refaktorierungen, wiederkehrendem Standardcode, Tests und dem Erkunden des Codes. Entwickler verantworten das fachliche Modell, die Architektur und die Prüfung.
"KI ersetzt keine technische Sorgfalt. Gute Typen sollten fachliche Bedeutung ausdrücken. Kommentare sollten nur erklären, was der Code nicht selbst zeigen kann. Unser Ziel ist nicht mehr Text für den Agenten, sondern besserer Kontext. So beschleunigt KI die Arbeit an einem komplexen System, ohne den Aufbau technischer Schulden zu beschleunigen."
Wir arbeiten mit mittelständischen B2B-Unternehmen, insbesondere in Deutschland, der EU und den USA. Unsere Web Entwicklung umfasst komplexe Plattformen und Integrationen, die dauerhaft technische Verantwortung erfordern. Derselbe Ansatz unterstützt ERP-, CRM- und Hochlastsysteme sowie die KI-Integration.
Klare Verantwortungsgrenzen sind auch wichtig, wenn Automatisierung kundenbezogene Abläufe erreicht. Bei Google SEO müssen technische Änderungen vor der Freigabe validiert werden. Bei GEO SEO brauchen veröffentlichte Aussagen über das Unternehmen eine verlässliche Quelle. Im Online Marketing müssen automatisierte Tracking-Änderungen auf die Anforderungen an die Einwilligung geprüft werden.
Der geschäftliche Nutzen: Systeme sicherer und effizienter weiterentwickeln
Das geschäftliche Ziel ist ein System, das auch bei Veränderungen verständlich bleibt. Klarer Code hilft Entwicklern und Agenten, die Auswirkungen einer Anforderung vor der Änderung einzuschätzen. Das unterstützt eine besser planbare Wartung, ohne eine bestimmte Einsparung zu garantieren.
Betrachten Sie eine Unternehmenswebsite, die mit einem Kundenportal und einem ERP-System verbunden ist. Eine Änderung daran, welche Kunden ein Angebot nutzen dürfen, kann jede Schicht betreffen. Klar benannte fachliche Regeln und dokumentierte Integrationsgrenzen helfen dem Team, diese Abhängigkeiten vor der Freigabe zu finden.
Bei einer Modernisierung beginnen wir mit den Regeln, die sich aus dem bestehenden Code am schwersten rekonstruieren lassen. Für die KI-Automatisierung legen wir fest, was der Agent ändern darf und was eine Freigabe benötigt. Nützliche Messgrößen sind Nacharbeiten aus Codeprüfungen, erst nach der Freigabe entdeckte Fehler und die Zeit zur Validierung einer Änderung.
Sprechen Sie mit Webdelo über die Entwicklung oder Modernisierung eines komplexen B2B- oder ERP-Systems. Oder über die Integration von KI-Automatisierung in Ihre Entwicklungs- und Geschäftsprozesse. Beginnen Sie mit dem Ablauf, den Sie verbessern möchten, und den fachlichen Regeln, die dabei erhalten bleiben müssen.
Besserer Kontext statt mehr Text
Nützliche Codekommentare für KI-Programmieragenten erklären, was der Code nicht zeigen kann. Drücken Sie fachliche Bedeutung zuerst durch Typen und Namen aus. Nutzen Sie Kommentare für verborgene Gründe und halten Sie sie bei Änderungen am System aktuell.
Gültiger Code ist nur der Anfang. AI First funktioniert, wenn Entwickler weiterhin Architekturentscheidungen treffen, Änderungen prüfen und für das Verhalten im Produktivbetrieb verantwortlich bleiben.
Häufig gestellte Fragen
Was sollten Codekommentare für AI Coding Agents erklären?
Ein guter Kommentar erklärt das Warum, nicht das Was. Er bewahrt Wissen, das sich aus dem umliegenden Code nicht erschließen lässt: einen fachlichen Grund, eine Architekturregel, eine Einschränkung einer Schnittstelle, eine Regel für Nebenläufigkeit oder eine bewusste Auslassung. Kommentare wie "Status aktualisieren" über offensichtlichem Code bringen nichts. Bei Webdelo gilt: Mit Typen ausdrücken, was sich typisieren lässt, benennen, was sich benennen lässt, und kommentieren, was sich nicht erschließen lässt.
Warum sind Namen und Typen für einen Coding Agent wichtig, wenn der Code ohnehin läuft?
Ein Compiler folgt nur den Regeln der Sprache. Code mit einem Namen wie $x1 läuft deshalb genauso wie Code mit $availableCredit. Ein Coding Agent nutzt zusätzlich Namen, Typen, Kommentare, Tests und den Kontext des Repositorys, um die Absicht des Codes zu erkennen. Fehlt ein aussagekräftiger Name, fehlt dem Agenten ein Hinweis darauf, wo eine Änderung hingehört. Gültiger Code ist nicht gleich verständlicher Code.
Wie verringern fachliche Typen den Bedarf an Kommentaren und PHPDoc?
Fachliche Typen wie SettlementAccountId, Money und SettlementStatus tragen eine fachliche Bedeutung, die int und string nicht haben. Werkzeuge können sie prüfen. Ein Aufrufer kann dann keine Kunden-ID mehr übergeben, wo eine Konto-ID erwartet wird. Eine Beschreibung in PHPDoc nennt die Regel nur, erzwingt sie aber nicht. Mit fachlichen Typen bleibt für Kommentare das Warum einer Regel übrig.
Wann lohnt sich PHPDoc weiterhin?
PHPDoc ist sinnvoll, wenn es etwas aussagt, das native Typen nicht ausdrücken können. Typische Fälle sind ältere Schnittstellen mit unvollständigen Typen, Array-Strukturen, generische Typen für die statische Analyse, Verträge, Maßeinheiten, Einschränkungen externer Schnittstellen, Ausnahmen und Nebenwirkungen. Eine Zeile wie "@param OrderStatus $status Order status" wiederholt nur die Signatur. Eine einfache Prüffrage hilft: Sagt diese Zeile dem Leser etwas, das die Signatur nicht sagt?
Wie kann ein einzelner Kommentar einen Deadlock in Go-Code verhindern?
Manchmal hält der aufrufende Code bereits einen Mutex, bevor er eine Hilfsfunktion aufruft. Ein Agent oder ein neuer Entwickler, der nur die Hilfsfunktion sieht, könnte eine weitere Sperre hinzufügen, um die gemeinsamen Daten zu schützen. Denselben Go-Mutex erneut zu sperren blockiert den Aufruf dauerhaft, und eine zweite Sperre kann einen Deadlock auslösen. Ein kurzer Kommentar, dass der Aufrufer die Sperre hält, macht diese Regel sichtbar. Prüfung aller Aufrufer und Tests für Nebenläufigkeit bleiben trotzdem nötig.
Schaden redundante Kommentare AI Coding Agents?
Ja. Ein Agent kann nur eine begrenzte Menge an Material gleichzeitig berücksichtigen. Wiederholtes PHPDoc und zeilenweises Nacherzählen belegen diesen Platz, ohne Bedeutung hinzuzufügen. Veraltete Kommentare sind schlimmer, weil sie dem Agenten eine zweite, widersprüchliche Version der Regeln liefern. Namen zu kürzen, um Tokens zu sparen, ist keine Lösung: Aussagekräftige Namen sind nützliches Signal. Webdelo verspricht keinen festen Prozentsatz an eingesparten Tokens, Kosten oder Fehlern.
Sollten AI Coding Agents Kommentare schreiben, und worin unterscheidet sich AI First von Vibe Coding?
Ja, aber nicht mit der Regel "jede Methode kommentieren". Projektanweisungen sollten Kommentare nur für nicht offensichtliche Geschäftsregeln, Regeln der Architektur und Nebenläufigkeit, bewusste Auslassungen, Besonderheiten externer Systeme sowie Vorgaben zu Sicherheit und Compliance verlangen. Das gehört zu AI First mit Human in the Loop: Agenten helfen bei klar begrenzten Aufgaben, Entwickler verantworten Fachmodell, Architektur und Prüfung. Ein starkes Modell beschleunigt auch eine schlecht gestaltete Umgebung, deshalb entscheidet weiterhin die Disziplin im Engineering über das Ergebnis.
