Code-Review-Kommentare schneller per Spracheingabe schreiben

Ein hilfreicher Code-Review-Kommentar sagt nicht nur, was falsch aussieht. Er beschreibt das Verhalten, erklärt dessen Bedeutung und macht den nächsten Schritt deutlich. Solche Erklärungen immer wieder zu tippen, kann den Lesefluss unterbrechen. Ein kurzer Hinweis wie „Leerfall behandeln“ lässt dagegen oft wichtige Fragen offen.

Mit Spracheingabe kannst du deine Begründung festhalten, solange der Gedankengang noch präsent ist. Lass auf deinem Mac den Diff geöffnet, beginne einen Kommentarentwurf und erkläre das Problem wie im Gespräch mit einem Teammitglied. Überarbeite den Text anschließend vor dem Absenden. Das Diktieren erfasst deine Erklärung; es prüft weder den Code noch die Richtigkeit einer Änderung.

1. Erst die Grundlage klären, dann sprechen

Beschränke jeden Kommentar auf einen Punkt. Notiere die betroffene Zeile oder Funktion, die Eingabe beziehungsweise Situation und das beobachtete oder erwartete Verhalten. Wenn du den Code nicht ausgeführt hast, kennzeichne deine Einschätzung als Ergebnis der Codelektüre. Ein möglicher Fehler ist noch kein reproduzierter Fehler.

Überlege außerdem, welche Antwort du brauchst:

• Erforderliche Änderung: Benenne das konkrete Problem oder die vereinbarte Anforderung, die vor der Freigabe erfüllt werden muss.
• Vorschlag: Mach deutlich, dass die Verbesserung optional ist.
• Frage: Bitte um Kontext, wenn noch unklar ist, ob überhaupt eine Änderung nötig ist.

Nutze die Konventionen deines Teams. Eine persönliche Vorliebe wird nicht allein durch eine bestimmte Formulierung zu einem Grund, die Freigabe zu blockieren.

2. Die Begründung diktieren, genaue Angaben ergänzen

Erkläre drei Dinge: „In dieser Situation fällt mir dieses Verhalten auf. Das hat diese Auswirkung. Können wir diese Änderung oder Prüfung vornehmen?“ Mach zwischen den Gedanken kurze Pausen und bleibe bei einem Thema.

Füge genaue Bezeichner, Dateipfade und Codeausschnitte anschließend direkt aus dem Quelltext ein. Bei Code, dessen Bedeutung von einzelnen Zeichen abhängt, solltest du dich nicht allein auf die Spracherkennung verlassen. Streiche Wiederholungen und beziehe dich auf die Implementierung und ihre Wirkung, nicht auf die Person dahinter.

3. Aus einer vagen Notiz wird konkretes Feedback

Das folgende fiktive Beispiel setzt voraus, dass das Verhalten lokal reproduziert wurde.

Erste Notiz: „Die leere Suche muss korrigiert werden.“

Überarbeiteter Kommentar:

Erforderliche Änderung — leere Suche: Wenn ich eine Suche nur mit Leerzeichen absende, bleibt der Ergebnisbereich im Ladezustand. Ich habe das mit der aktuellen Änderung lokal reproduziert. Nutzende erhalten weder Ergebnisse noch einen Hinweis darauf, was sie als Nächstes tun können.

Können wir Eingaben, die nur aus Leerzeichen bestehen, vor dem Suchstart abfangen und den vereinbarten Hinweis für eine leere Eingabe anzeigen? Bitte ergänze auch einen Test für diesen Ablauf, damit wir prüfen können, ob der Ladezustand korrekt beendet wird.

Vermutest du den Fehler lediglich, beginne etwa mit „Beim Lesen dieses Zweigs scheint es, als ob …“ und frage, ob ein anderer Ablauf den Fall bereits abdeckt. Ist der Hinweistext noch nicht abgestimmt, kläre zuerst das gewünschte Verhalten, statt eine Anforderung vorauszusetzen.

4. Eine kurze Vorlage wiederverwenden

Art: [Erforderliche Änderung / Vorschlag / Frage]

Kontext: Bei [Stelle oder Situation] tritt [beobachtetes Verhalten oder ausdrücklich vermutetes Problem] auf.

Auswirkung: Das ist relevant, weil [konkrete Folge].

Nächster Schritt: Können wir [gezielte Änderung, Prüfung oder Erklärung]?

Grundlage: [Reproduktionsschritte, relevante Anforderung oder Testergebnis, falls vorhanden].

Die Felder sind Denkhilfen, keine Pflichtüberschriften. Für einen kleinen Vorschlag reichen oft zwei Sätze. Betrifft ein Thema mehrere Dateien, fasse es im Gesamtkommentar zum Review zusammen und verlinke die passenden Stellen, statt denselben Hinweis mehrfach zu posten.

5. Vor dem Absenden gegenlesen

Gleiche Namen, Verneinungen und Fachbegriffe mit dem Diff ab. Prüfe, ob aus „wird“ versehentlich „wird nicht“ geworden ist und ob genannte Testergebnisse tatsächlich vorliegen. Lies den Kommentar aus Sicht der anderen Person: Ist klar, welche Antwort oder Änderung du erwartest?

Passende Ergänzungen findest du in den Anleitungen zu Pull-Request-Beschreibungen und verständlichen Fehlerberichten.

TypeFree bietet einen einfachen Weg, Sprache in bearbeitbaren Text umzuwandeln und schneller zu schreiben. Diktiere die Begründung für deinen nächsten Code-Review-Kommentar, prüfe die Details und veröffentliche Feedback, das den nächsten Schritt erleichtert.