Code-Review-Kommentare formulieren, mit Vorher-nachher-Beispielen

Du liest einen Pull Request, stolperst über eine Stelle und tippst schnell "Warum machst du das so?". Gemeint war eine echte Frage. Angekommen ist ein Vorwurf. Ein Review-Kommentar ist die kurze Rückmeldung, die du an eine Zeile oder einen Abschnitt einer vorgeschlagenen Änderung schreibst. Tonfall, Mimik und Körpersprache fehlen dabei, ebenso die kurze Nachfrage im Vorbeigehen. Den Ton macht hier allein die Wortwahl. Sie entscheidet auch, ob klar wird, was zu tun ist. Hier erfährst du, wie ein hilfreicher Kommentar aufgebaut ist, wie du Pflicht von Vorschlag trennst und wie sich vier typische Kommentare umformulieren lassen.

Woraus ein hilfreicher Kommentar besteht

Bevor es um Kennzeichnungen wie "Nit:" geht, hilft ein einfaches Gerüst aus vier Bausteinen. Nicht jeder davon muss in jedem Kommentar stehen. Alle Beispiele in diesem Artikel sind erfunden, ebenso die Datei-, Funktions- und Variablennamen darin.

1. Der Code statt die Person. Google empfiehlt in seinen Engineering Practices, Kommentare freundlich, klar und respektvoll zu schreiben. Gerade bei heiklen Punkten soll sich der Kommentar auf den Code beziehen und nicht auf die Person, die ihn geschrieben hat. Aus "Du hast den Cache falsch verstanden" wird dann "loadProfile liest den Cache auch bei abgelaufenen Einträgen".
2. Die konkrete Beobachtung. Nenn die Datei, die Funktion und den Fall, um den es geht. "Hier fehlt was" zwingt die andere Person zum Raten, und geraten wird meistens falsch.
3. Der Grund, wo er nicht offensichtlich ist. Eine Begründung kann die Absicht hinter deinem Hinweis erklären, eine Vorgehensweise, an die ihr euch haltet, oder den Nutzen für den Code. Google hält ausdrücklich fest, dass nicht jeder Kommentar eine solche Erklärung braucht. Ein Tippfehler bleibt ein Tippfehler.
4. Der nächste Schritt. Hier wägst du ab zwischen "Problem benennen" und "Lösung vorgeben". Laut Google bleibt die Person, die die Änderung geschrieben hat, für die Korrektur verantwortlich. Sie ist näher am Code und kann deshalb die bessere Lösung finden.

Was "Nit:", "Optional:" und "FYI:" bedeuten

Bei vielen Kommentaren bleibt eine Frage offen. Muss ich das ändern, bevor die Änderung durchgeht? Zwei verbreitete Systeme beantworten sie mit einem kurzen Präfix.

Googles Leitfaden für Review-Kommentare nennt drei Kennzeichnungen. "Nit:" steht für eine Kleinigkeit, die technisch trotzdem geändert werden sollte. "Optional:" oder "Consider:" steht für eine Idee, die nicht nötig ist. Bei "FYI:" erwartest du in der aktuellen Änderung nichts, der Hinweis ist zum Nachdenken gedacht.

Conventional Comments schlägt eine festere Form vor, nämlich <label> [decorations]: <subject> und darunter bei Bedarf eine Erklärung mit Kontext, Gründen und nächsten Schritten. Für den Alltag reichen vier Labels. "issue" benennt ein Problem, "suggestion" einen Verbesserungsvorschlag, "question" eine mögliche Schwierigkeit, deren Bedeutung du noch nicht einschätzen kannst, und "nitpick" eine kleine, geschmacksabhängige Bitte. Dazu kommen Zusätze in Klammern. "blocking" hält die Freigabe auf, "non-blocking" nicht.

Ein Haken bleibt. "Nit" heißt nicht überall dasselbe. Bei Google ist die Änderung klein, aber gewünscht. Bei Conventional Comments ist "nitpick" geschmacksabhängig und blockiert grundsätzlich nicht. Wer das Wort ohne Absprache benutzt, verlässt sich auf eine Bedeutung, die die andere Seite vielleicht anders gelernt hat.

Die Konvention deines Teams geht also vor. Conventional Comments erlaubt ausdrücklich, von der vorgeschlagenen Liste abzuweichen, und rät bei den Zusätzen in Klammern zu einem kleinen, eindeutigen Satz. Benutzt ihr gar keine Labels, tut es ein klarer Satz am Ende des Kommentars, etwa "Das sollte vor dem Merge rein" oder "Nur ein Vorschlag, nichts Nötiges".

Vier Kommentare vorher und nachher

Jedes Beispiel zeigt zuerst einen Kommentar, wie er oft geschrieben wird, und danach eine Fassung mit den vier Bausteinen.

Fehlender Testfall

Vorher: "Hier fehlen Tests."

issue (blocking): parseDuration hat keinen Test für negative Werte. Genau dort kam im letzten Release der Fehler mit den Minuszeiten her. Kannst du einen Fall dafür ergänzen?

Der Kommentar nennt die Funktion, den ungetesteten Fall und den Grund. Und er sagt, dass die Freigabe daran hängt.

Vermuteter Fehlerfall

Vorher: "Das kann so nicht funktionieren."

question: In sendReminder wird userId ohne Prüfung weitergereicht. Was passiert, wenn die Funktion aus dem nächtlichen Job kommt? Den Code an dieser Stelle kenne ich nicht gut genug.

Aus einem Urteil wird eine Frage, die wirklich eine ist. Der letzte Satz sagt offen, warum du fragst.

Unklare Benennung

Vorher: "Schlechter Name."

Nit: data2 sagt wenig darüber, was drinsteht. Wie wäre normalizedRows? Kein Grund, die Freigabe aufzuhalten.

Der Zusatz im letzten Satz löst die Mehrdeutigkeit von "Nit" auf, ohne dass ihr euch vorher auf ein System einigen müsst.

Optionaler Umbau

Vorher: "Man könnte das auch ganz anders lösen."

Optional: Die vier if-Zweige in resolveTier ließen sich als Tabelle mit den Grenzwerten schreiben. Neue Stufen wären dann eine Zeile statt eines Zweigs. Muss aber nicht in diesen Pull Request.

Alle vier Fassungen nennen eine Stelle, ein Verhalten und die Wichtigkeit. Mehr braucht es in den meisten Fällen nicht.

Echte Fragen stellen und Kleinigkeiten bündeln

Conventional Comments rät in seinen Hinweisen zu schriftlichem Feedback, dort zu fragen, wo dir wirklich Kontext fehlt. Das ist etwas anderes als eine Anweisung im Fragegewand. "Meinst du nicht, dass das in eine eigene Funktion gehört?" klingt offen, lässt der anderen Person aber keine Wahl und zwingt sie, deine Absicht zu erraten. Willst du die Änderung, dann schreib sie hin: "Bitte zieh das in eine eigene Funktion, die Methode macht sonst drei Dinge."

Der zweite Punkt betrifft Kleinkram. Zehn einzelne Kommentare zur selben Formatierungsfrage erzeugen zehn Benachrichtigungen und lassen ein Review größer wirken, als es ist. Bündle ähnliche Punkte in einem Kommentar, nenn ein oder zwei Beispiele und sag, wie sie sich auf einen Schlag auflösen lassen.

Prüf jeden Kommentar am Ende mit einer Frage. Kann die andere Person daran erkennen, was sie tun muss, um ihn abzuhaken?

Gelungenes ansprechen und den Grund nennen

Google empfiehlt, auch Stellen zu kommentieren, die dir gefallen, und dabei zu sagen, warum. Der Grund macht den Unterschied. "Sieht gut aus" bleibt Dekoration, ein konkreter Bezug ist eine Information.

praise: rejectsExpiredToken erklärt das erwartete Verhalten besser als jeder Kommentar. Den Aufbau übernehme ich für die anderen Auth-Tests.

Pflicht ist das nicht, und ein technischer Hinweis wird dadurch auch nicht ersetzt. Ein ehrlicher Satz zur richtigen Stelle kostet aber wenig.

Mit Yappee den Review-Kommentar sprechen

Das Formulieren kann mehr Zeit kosten als das Lesen des Codes. Du weißt nach zehn Sekunden, was dich stört, und tippst danach drei Anläufe, bis der Satz weder schroff noch schwammig klingt.

Dafür hat Yappee das Format "Code-Review-Kommentar". Du sprichst dein Feedback aus und bekommst einen Review-Kommentar, den du auf GitHub, GitLab oder in einem ähnlichen Werkzeug einfügst. Yappee läuft auf iPhone und Mac und unterstützt mehr als 50 Sprachen bei Transkription und Übersetzung. Läuft das Review auf Englisch, sprichst du in deiner Sprache und lässt den Kommentar auf Englisch ausgeben.

1. Sprich die Stelle, die Beobachtung, den Grund und die gewünschte Wichtigkeit aus, also die vier Bausteine von oben.
2. Wähl das Format "Code-Review-Kommentar" und lies den Text durch.
3. Prüf vor dem Einfügen die Datei-, Funktions- und Variablennamen sowie das Label, auf das sich dein Team geeinigt hat.

Yappee arbeitet mit dem, was du sagst. Bleibt deine Beobachtung vage, bleibt auch der Kommentar vage. Die App hängt sich nicht in GitHub oder GitLab ein, du fügst den Text selbst ein. Und für ein "Nit: Tippfehler" bist du mit Tippen schneller, als du die Aufnahme startest.

Das Muster dahinter bleibt gleich, ob du sprichst oder tippst. Nenn die Stelle, sag, was dir auffällt, gib den Grund dazu, wenn er nicht auf der Hand liegt, und mach sichtbar, ob du eine Änderung erwartest.