Bitte haltet Code-Erklärungen einfach

• Wenn bei Code-Reviews lange Erklärungen zusammen mit großen Diffs ankommen, fällt es Reviewerinnen und Reviewern schwer, den entscheidenden Grund für die Änderung zu erkennen; daher sollten Commit-Messages, Merge-Request-Beschreibungen und Kommentare knapp sein
• Erklärungen sollten sich weniger darauf konzentrieren, was geändert wurde, sondern vor allem darauf, warum es geändert wurde; viele Änderungen lassen sich bereits im Code selbst erkennen
• Lange Erklärungen, die den gesamten Kontext auf einmal unterbringen wollen, können bei manchen Reviewern die Konzentration und das Review-Tempo verringern
• In Merge-Reviews sind atomare Commits besonders wichtig; kleine Korrekturen lassen sich mit git amend erledigen, das Aufräumen vor dem Merge per Rebase oder Squash
• Auch wenn LLM-Tools genutzt werden, ist es hilfreicher für das Codeverständnis und die Zugänglichkeit von Reviews, Kommentare, Erklärungen und Commit-Messages selbst zu schreiben

---

Review-Erklärungen sollten sich eher auf das „Warum“ als auf das „Was“ konzentrieren

• Wenn Erklärungen, Commits und Merge Requests in Code-Reviews mit zu vielen Informationen überladen sind, steigt der Prüfaufwand
• Statt Änderungen ausführlich aufzuzählen, sollte vor allem klar beschrieben werden, warum sie vorgenommen wurden
• Der Code selbst kann den Großteil der Änderungen zeigen, und fehlenden Kontext können Reviewer bei Bedarf nachfragen
• Erklärungen, die wie lange Texte geschrieben sind, können Reviews für Menschen, denen längere Konzentration schwerfällt, verlangsamen
• Commit-Messages, Merge-Request-Beschreibungen und Code-Kommentare sollten klar und auf den Punkt sein und nur die nötigen Informationen enthalten

Bitte zu Commit-Aufbereitung und zur Nutzung von LLMs

• Commits sollten besonders in Merge-Reviews atomar sein, sodass jede Änderung für sich verstanden werden kann
• Kleine Korrekturen können mit git amend eingearbeitet werden; vor dem Merge kann per Rebase aufgeräumt oder gesquasht werden
• Auch bei der Nutzung von LLM-Tools ist es besser, Kommentare, Erklärungen und Commit-Messages selbst zu schreiben
  • Das eigene Schreiben hilft dabei, die Änderungen besser zu verstehen
  • Selbst verfasste Erklärungen können für Reviewer leichter zugänglich sein
• Es wird auch die persönliche Meinung geäußert, dass man LLM-Tools möglichst vermeiden sollte
• Es gab Reaktionen auf den Begriff Zugänglichkeit, aber der Kern der Bitte ist, Erklärungen in Code-Reviews knapper und leichter prüfbar zu machen

[GN⁺]

Lobste.rs-Meinungen

• Man sollte vorsichtig sein, Accessibility-Anforderungen mit den spezifischen Vorlieben einzelner Personen gleichzusetzen.
  Nur weil jemand ADHS hat, heißt das nicht, dass eine Abneigung gegen lange Commit-Messages ein allgemeines ADHS-Merkmal ist; Accessibility bedeutet eher eine angemessene Anpassung, die normalen Nutzern keine übermäßige Last auferlegt, nicht „alles so machen, wie es Menschen mit ADHS mögen“.
  Deshalb liegen viele Accessibility-Funktionen hinter Einstellungen, die Einzelne selbst wählen können, etwa hoher Kontrast, reduzierte Bewegung oder Dark Mode.

  • Ich hätte es klarer formulieren können, aber mein AuDHD braucht bestimmte Bedingungen, um richtig arbeiten und funktionieren zu können.
    Lange Textblöcke, etwa wenn selbst kleine Änderungen mit Erklärungen im Umfang von zwei A4-Seiten versehen werden, können mich bei der Arbeit komplett blockieren, und wenn ich mich zum Lesen zwinge, führt das leicht zu Burnout.
    Wahrscheinlich hätte ich eher sagen sollen: „Das ist eine Accessibility-Anforderung von mir, und ich weiß, dass es viele ähnliche Menschen gibt.“
    Man könnte es trotzdem auch als Vorliebe sehen, aber wenn jemand mit LLM erzeugte Textwände an Commit-Messages hängt, dann bitte mit Menschen wie mir im Hinterkopf.
  • Das ist zwar individuell verschieden, aber „komm bitte zuerst zum Punkt“ halte ich durchaus für eines der zentralen ADHS-Merkmale.
    Auch unter Accessibility-Gesichtspunkten profitieren letztlich alle von dieser Anpassung, daher sehe ich keinen guten Grund, sich dagegen zu stellen.
  • Meiner Erfahrung nach entsteht ein großer Teil der unnötigen Schwierigkeiten, die neurodivergente und behinderte Menschen erleben, daraus, dass man Accessibility-Anforderungen als Geschmackssache abtut.
    Wenn Accessibility verbessert wird, profitieren auch Menschen davon, die diese Funktionen nicht zwingend brauchen, um auf einer gleicheren Ausgangslinie zu stehen; deshalb ist es gut, in diese Richtung zu gehen.

• Ich mochte schon lange vor AI übermäßig detaillierte Kommentare, und viele Leute, mit denen ich gearbeitet habe, fanden das überraschend.
  Zum Beispiel gibt es diese Methode: https://github.com/ghostty-org/ghostty/…
  Ich schreibe seit etwa 15 Jahren sprachunabhängig im Wesentlichen in diesem Stil und habe das im AI-Zeitalter auch ausdrücklich in AGENTS.md festgehalten.
  Die verlinkte Datei und die Kommentare darin sind vollständig von Menschen geschrieben, ganz ohne AI.
  Der Grund ist einfach: Dadurch wird eine Regel doppelter Eintragung erzwungen, nach der Kommentar und Code zueinander passen müssen.
  Wenn sie nicht zusammenpassen, ist entweder der Kommentar falsch oder der Code oder beides, und schon die Frage „welches von beidem stimmt?“ hat viele Probleme aufgedeckt.
  Am Ende finde ich, dass in einem eigenen Projekt jede Person so kommentieren sollte, wie sie es möchte.

  • Ich bekomme auch manchmal den freundlichen Scherz zu hören, dass ich mehr Kommentare als Code schreibe, aber ich mag solche Kommentare wirklich sehr.
    Wenn ich den Code später erneut lese, bewahren sie den Kontext lokaler Entscheidungen, die ich damals getroffen habe, und sie helfen auch Reviewer:innen oder Menschen, die den Code zum ersten Mal sehen, beim Aufbau dieses Kontexts.
    Solche Kommentare sind zwar ausführlich, aber nicht die „unnötigen Details“, von denen im Artikel die Rede ist, und das geteilte Beispiel scheint mir ein gutes Beispiel für die Maxime „erkläre nicht das Was, sondern das Warum“ zu sein.
  • Solche Kommentare sind großartig.
    Ein Kommentar wie im Beispiel, der erklärt, warum macOS-Nutzer ihre Shell-Konfiguration in ~/.bash_profile packen und dann eine Login-Shell erwarten, liefert nützlichen Kontext dafür, warum eine bestimmte Entscheidung getroffen wurde.
    Wenn wir aber zu LLM zurückkommen: Ich persönlich habe noch keinen von LLM erzeugten Kommentar von solcher Qualität gesehen.
    Meistens bleibt es bei Wiederholungen von Dingen, die beim Lesen des Codes ohnehin offensichtlich sind: foo() macht dies, dann macht es bar(), und am Ende baz.
  • Mit Kommentaren der verlinkten Art habe ich kein Problem.
    Das Problem ist das Chaos, bei dem selbst an sehr kleine Änderungen riesige Tabellen und Aufzählungslisten gehängt werden.
  • Für diesen Detaillierungsgrad bin ich wirklich dankbar, aber persönlich hätte ich das lieber in der Commit-Message des Commits, der diese Methode eingeführt hat, als im Kommentar.
    Commit-Messages bleiben als Aufzeichnung immer an denselben Zeitpunkt gebunden, während Kommentare meiner Meinung nach mit der Zeit auseinanderdriften können.
  • Der Kommentar ab Zeile 1467 ist ein Meisterwerk, und man spürt die Erschöpfung direkt.

• Bei der Arbeit habe ich höflich in die PR-Vorlage geschrieben: „Bitte erläutere direkt die Motivation dieser Änderung und die wichtigen Designentscheidungen, auf die man im Review achten sollte.“
  Aber in neun von zehn Fällen wirft das jeweils verwendete LLM die gesamte Vorlage weg und spuckt stattdessen eine lange Erklärung aus, inklusive Anzahl hinzugefügter Tests, bestandener Checkboxen und langatmiger Abschweifungen über Nebensächlichkeiten.
  Das macht Reviews natürlich zu einem großen Vergnügen.

  • Bei uns im Job gibt es dasselbe Problem.
    Ich weiß nicht, wer dachte, es sei eine gute Idee, überall Tools für LLM-generierte Commit-Messages einzubauen, aber am Ende hat man in Commits genau dieses https://noslopgrenade.com/-Problem.
    In der Commit-Message oder der Pull-Request-Beschreibung fehlt dann nützlicher Kontext wie Änderungsmotivation, Designentscheidungen oder Begründungen, und stattdessen wird alles zu ausformulierten Absätzen über Implementierungsdetails, die man auch direkt aus dem Code lesen kann.
  • Ich habe dasselbe Verhalten beobachtet.
    Ich denke darüber nach, in agents.md hinzuzufügen: „Wenn du Commit-Messages schreibst, orientiere dich an commit-messages.md.“
    In commit-messages.md könnte man dann Richtlinien für Commit-Messages festhalten, etwa keine Checkboxen für bestandene/fehlgeschlagene Tests und einzelne Tests nicht aufzählen, sondern zusammenfassen oder ganz weglassen.

• Ich schreibe nur dann Kommentare dazu, was ich tue, statt warum ich es tue, wenn ich mir nicht sicher bin, ob die Vorgehensweise richtig ist.
  Ein typischer, immer wieder schmerzhafter Auslöser dafür sind reguläre Ausdrücke.

  • Bei mir genauso.
    Manchmal muss man alles solide erklären, aber inzwischen sehe ich sogar bei kleinen Änderungen wie dem Umbenennen von Variablen riesige Erklärungen.

• Interessanterweise wurde mir eher oft gesagt, dass meine Commit-Messages zu kurz seien.

  • Diese Diskussion in dem Artikel steht gewissermaßen in der Gegenrichtung neben dem Beitrag Chesterton middle finger, der sich darüber beklagt, dass Erklärungen zu kurz sind.
  • Zu kurz kann es natürlich auch sein, aber dort gleich einen ganzen Roman hineinzupacken, ergibt ebenso wenig Sinn.
  • LLM schreibt wirklich viel zu viel.
    Deshalb habe ich claude so konfiguriert, dass es überhaupt keine Kommentare mehr schreibt, weil ich ohnehin 98 % davon manuell gelöscht und die verbleibenden 2 % auch noch neu formuliert habe.

• Ich mag in der Regel sehr ausführliche Commit-Messages, bevorzuge aber eine Struktur wie bei einem Nachrichtenartikel, bei der die wichtigsten Informationen zuerst stehen und weniger wichtige, aber weiterhin relevante Details danach kommen
  Zum Beispiel packt man in den Titel die wichtigsten Informationen so dicht wie möglich, im ersten Absatz erklärt man die Änderung in weniger komprimierten Sätzen, und in den folgenden Absätzen stehen zusätzliche Details zur Art der Codeänderung, die man nicht im Detail lesen muss, solange sie nicht wirklich schwer zu verstehen ist
  Es scheint, als würde unterschätzt, wie wichtig Commit-Messages für Menschen sind, die den Code später lesen
  Wenn ich mich durch eine Codebasis grabe und mich frage, warum ein bestimmter Block so aussieht, war ich nie enttäuscht, wenn git blame zu einer Commit-Message führte, die quälend detailliert erklärte, dass das, was unbeholfen aussah, in Wirklichkeit die verbleibende Wahl nach mehreren besseren wirkenden, aber unvollständigen Ansätzen war
  Um auf den Kern der Aussage des Autors zurückzukommen: Explizite Markierungen in die Kommunikation einzubauen, ist eine gute Anpassung und allgemein nützlich
  In eine Commit-Message kann man mitten im Text einen Satz wie „Wenn du diesen Code gerade reviewst, kannst du hier aufhören zu lesen“ einfügen

• Mit „Unnötige Details kann man bei Bedarf erfragen“ nimmt man ziemlich kühn an, dass die betreffende Person weiterhin verfügbar sein wird
  Ich habe angefangen, mir bei Commit-Messages Mühe zu geben, als ich begann, zu einer über zehn Jahre alten FLOSS-Codebasis beizutragen
  Die einzige Möglichkeit, mehr darüber herauszufinden, warum der Code so existierte, war Git-Archäologie, und ich habe gelernt, Emacs’ vc-annonate zu benutzen, um das leicht nachzuverfolgen
  Auch in Arbeitscode gab es mehrfach Fälle, in denen der ursprüngliche Autor der von mir gepflegten Codebasis schon lange nicht mehr da war
  Commit-Messages werden nicht nur während des Reviews gelesen; tatsächlich blenden viele Review-UIs Commit-Messages aus
  Das Problem scheint eher nicht die lange Commit-Message an sich zu sein, sondern schlecht geschriebene Commit-Messages
  Die Leitlinie „Schreibe Commit-Messages, Merge-Request-Beschreibungen und Codekommentare klar, auf den Punkt und bedarfsorientiert, und erkläre nicht das Was, sondern das Warum“ wirkt sinnvoll
  Es könnte auch ein Problem sein, wenn jemand, der früher nur Fix Bugz 🚀️ schrieb, jetzt „Best Practices“ folgen will und Commit-Messages mit einem LLM schreibt
  Meine Hypothese ist, dass die meisten Menschen Commit-Messages nicht schreiben, weil sie sie nicht lesen, und sie lesen sie nicht, weil die Aktivierungsenergie hoch ist, wenn man zum Durchsehen von Commits auf Dinge wie das GitHub-Webinterface angewiesen ist

  • „Unnötige Details kann man bei Bedarf erfragen“ bezieht sich auf das Review
    Wenn die Information wichtig ist, kann man sie als Kommentar hinterlassen oder zur Commit-Message hinzufügen
    KDE benutzt seit einigen Jahren GitLab

• Langfristig braucht es für erfolgreiche Git-Archäologie durch spätere Generationen ein Gleichgewicht
  Wegen Personalwechseln oder weil Kontext aus den Köpfen verschwindet, kann man diese scheinbar unnötigen Details später oft nicht mehr erfragen
  Der beste Zeitpunkt, diesen Kontext festzuhalten, ist, solange man ihn noch hat
  Vielleicht will man eigentlich, dass wichtige Details zuerst stehen und in einer klar abgegrenzten Struktur wie eine Übersicht organisiert sind

• PRs oder Code-Erklärungen sind nicht für das Was man getan hat, sondern für das Warum man es getan hat
  Sie sollten erklären, warum der Code diese Form hat und welche Gründe dahinterstehen
  Das ist gut für Reviews und hilft später auch dabei, in der Git-Historie nachzuvollziehen, warum der Code so aussieht

• Es ist wichtig, Code-Erklärungen einfach zu halten
  Denn was man nicht verstehen oder worauf man sich nicht konzentrieren kann, kann man nicht lesen
  Gleichzeitig geht bei der Softwareentwicklung viel Kontext verloren, und im Moment befindet sich dieser Kontext oft nur im Kopf des Autors, von Leuten, die mit ihm gesprochen haben, oder von Personen, die tief in den Code geschaut haben
  Aber ich denke, dieser Kontext sollte stärker mit dem Code verflochten sein, nicht weniger
  Man kann nicht immer mit dem Autor sprechen, also sollte es an einem Ort stehen, der jederzeit zugänglich ist und zusammen mit dem Code aktualisiert wird
  Im heutigen Entwicklungsablauf ist dafür meist die Git-Commit-Message der passendste Ort
  Eine Zusammenfassung ganz oben ist gut, aber ich würde empfehlen, auch zusätzliche Erklärungen zur Codeänderung zu hinterlassen
  Wenn man selbst Inhalte, die jetzt nicht wichtig erscheinen, als Kontext nach außen trägt, wird das zukünftige Ich dankbar sein
  Künftig braucht es dafür bessere Ansätze, als solchen Kontext nur in Commit-Messages unterzubringen, und deshalb mag ich persönlich Literate Programming, das mehr Raum bietet, das „Was“ und das „Warum“ des Codes zu erklären