Bessere Pull Requests: Tipps und Vorschläge

Code Reviews sind ein wichtiger Bestandteil eines jeden Software-Entwicklungszyklus. In Source Code Management-Werkzeugen wie Bitbucket werden Pull Requests eingesetzt, um Änderungen am Quelltext zu prüfen, bevor diese einen kritischen Zweig im Repository erreichen. Dabei sind Code Reviews auch eine der schwierigsten und aufwändigsten Tätigkeiten innerhalb des Software-Entwicklungsprozesses. Deshalb werden oft erfahrene Teammitglieder benötigt, die gemeinsam die Implementierung neuer Features prüfen, lesen, überdenken, bewerten und absegnen.

Aufgrund ebendieser Komplexität sind endlos lange „In Review“-Spalten auf agilen Boards während Sprint-Retrospektiven keine Seltenheit. Um Softwareteams dabei zu helfen, diese „In Review“-Spalten schneller zu leeren, hat Atlassian nun einige Vorschläge für Richtlinien für Code Reviews vorgestellt, die auf der langjährigen Erfahrung der eigenen Entwicklern basiert.

Pull Requests sind keine einfache Sache

Man muss zugeben: Einen Pull Requests zu prüfen ist nicht gerade einfach. Es obliegt dem Reviewer, vor der Integration sicherzustellen, dass der eingereichte Code korrekt ist und den hohen Qualitätsstandards entspricht. Es wird erwartet, dass ein Reviewer die entsprechenden Unterschiede (Diffs) und betroffenen Dateien ausführlich sichtet. Dabei muss der Prüfer verstehen, was der Pull Request an sich bezweckt, welcher Ansatz dabei gewählt wurde, was überhaupt getan wurde und wie diese Dateien zusammenpassen. Und obendrein sollen noch Verbesserungsvorschläge abgegeben und auf Tippfehler und Styling-Probleme geachtet werden. Das ist eine Menge Holz für einen Reviewer – ganz besonders im Falle großer Pull Requests.

Wie kann man angenehmere Pull Requests für Reviewer schaffen?

Setzt man den Produktmanager-Hut auf, ergibt sich folgendes Bild: Sind Pull Requests ein Produkt, dann sind Prüfer die Kunden. Und Kunden sollen am Ende das Produkt Pull Request kaufen, indem sie diese akzeptieren und sich die In Review-Spalte leert. Möchten wir in der Lage sein, dieses Produkt vernünftig zu managen, dann müssen wir den Kunden und Markt verstehen. Ganz einfach eigentlich. Da die meisten Pull Request-Autoren bereits schon einmal Prüfer waren ist es relativ einfach, sich in die Rolle des Reviewers zu versetzen und sich die Frage zu stellen: „Wie könnte ich das für mich angenehmer machen?“.

Kleinere Pull Requests stellen

Indem man Pull Requests in ihrem Umfang reduziert, lässt sich die Review-Zeit ebenfalls reduzieren. Da die Anfragen so klein sind, ist es für einen Prüfer ein leichtes, den Kontext und die Logik zu verstehen und entsprechend darauf zu reagieren.

Was tun, wenn die Problemstellung in ihrer Komplexität quasi explodiert, nachdem man mit der Arbeit begonnen hat?

Es passiert schnell, dass man den Blick für das große Ganze verliert, wenn man sich auf die Lösung eines Problems eingeschossen hat. Das Lösen eines Problem stellt leider nur einen kleinen Bruchteil der tatsächlich benötigten Zeit von Ticketerstellung bis zur Auslieferung zum Kunden dar. Die meiste Zeit wird mit Reviews, Qualitätssicherung und dem Veröffentlichungsprozess verbracht. Ein bisschen mehr Zeit ins herunterbrechen des Problems zu investieren, während man schon an der Lösung arbeitet, zahlt sich auf lange Sicht immer aus. Damit lassen sich endlose In Review-Kolonnen effektiv reduzieren.

Aber was tun, wenn es unmöglich vorherzusagen scheint, ob ein Pull Request zu groß wird. Oft merkt man dies erst, wenn es bereits zu spät ist und die Arbeit bereits begonnen wurde?

Riesiege Pull Requests entstehen schnell. Viel schwieriger ist es, kleine und in sich logisch geschlossene Anfragen zu erstellen. Diese kleinen Pull Requests sind einfach zu Prüfen, zu Veröffentlichen und erzeugen Velocity. Ein Mittel gegen ungehemmtes Wachstum können Time-Boxed Spikes sein, kleine Zeiteinheiten in welchen man schaut, ob sich ein Vorgang in noch kleinere Einheiten zerlegen lässt, bevor man den Code pusht. Es ist definitiv ratsam, sich die Zeit zum herunterbrechen zu nehmen, bevor man einen riesigen Commit (und Pull Request) erzeugt.

Sinnvolle Beschreibungen und Titel wählen

Sinnvolle Beschreibungstexte im Detailfeld sind fast genauso effektiv wie kleinere Pull Requests. Sich die Zeit zu nehmen, eine aussagekräftige Beschreibung der Änderungen zu verfassen ist wichtig. Denn gute Beschreibungstexte leiten einen Prüfer so viel wie möglich durch den Code und heben relevante Dateien hervor und gruppieren diese in Konzepte bzw. Probleme, die gelöst wurden.

Dies spart dem Reviewer eine Menge Zeit, denn jetzt müssen sie nicht mehr jede Datei einzeln betrachten, um herauszufinden was Sache ist. Im Anschluss daran ist es viel leichter die Logik hinter dem gewählten Vorgehen zu verstehen und darauf einzugehen. Der Autor eines Pull Requests ist die geeignetste Person für diese Aufgabe, da sie die Änderungen durchgeführt hat und alle Details im Kopf hat.

Gleiches gilt für einen nützlichen Titel, der mehr als nur der Vorgangsschlüssel sein sollte. Mit einem klaren Titel lässt sich in einem Satz beschreiben, welches Problem gelöst wurde und gibt dem Prüfer vorab etwas Kontext.

Vernünftige Commit-Messages

Nicht jede Zeile einer Git-Commit-Message muss perfekt sein, aber eine gute Commit-Message hilft Prüfern.

Zum Einen hilft dies bei den von Bitbucket automatisch generierten Pull Requests, da die Beschreibung der Commits im Pull Request zusammengefasst wird. Dadurch entsteht eine nette Auflistung der Codeänderungen und hilft Reviewern, die neben den Unterschieden (Diffs) auch die Commits lesen.

Commits thematisieren die Code-Ebene und so sollten Commit-Nachrichten auch nur Änderungen dieser Ebene beinhalten. Pull Requests sind zwar auch auf Code ausgerichtet, drehen sich aber um eine höhere, architekturell-konzeptionelle Ebene der Änderungen. Eine High-Level-Beschreibung hilft neben den eigentlichen Code-Änderungen bei der Historisierung der Probleme. Aus diesem Grund ist es zu empfehlen, in jeden Commit den JIRA Vorgangsschlüssel zu erwähnen. So kann ein Nutzer einen Commit immer auf den Pull Request beziehen, egal wo dieser Commit auftaucht. Damit lassen sich auch weniger aussagekräftige Commit-Messages sinnvoll weiter verwerten.

Selbst mit wunderbar aussagekräftigen Commit-Nachrichten ist eine gute Beschreibung aber zu empfehlen. Denn auch wenn die von Bitbucket automatisch generierten Beschreibungen auf den ersten Blick ausreichend erscheinen, ist eine konzeptionelle Erörterung, was getan wurde weit hilfreicher als nur der Commit-Log.

Als Faustregel für Commit-Messages gilt: Eine Commit-Message sollte stets thematisieren, WAS geändert wurde und WARUM. Das WIE ist nicht relevant. Das ist der Diff, und diesen muss man nicht wiederholen.

Kommentare helfen Reviewern Pull Requests zu verstehen

Haben Sie lediglich ein paar Formatierungen geändert? Ist an einer bestimmte Datei der Hauptteil der Änderungen durchgeführt worden? Ist eine Datei mit einer anderen aus dem gleichen oder einem anderen Pull Request verwandt? Mit Inline-Kommentaren oben in einer Datei lassen sich solche Hinweise anbringen und helfen einem Prüfer, durch die Änderungen zu navigieren.

Noch besser: Einen Pull Request ohne Reviewer erstellen, diesen selbst reviewen und mit Kommentaren für Hinweise versehen bevor man andere den Code sehen lässt.

Es ist aber wichtig zu behalten, dass Kommentare auf Pull Requests nicht dazu eingesetzt werden sollten, den Code zu erklären. Wer sich dabei ertappt, sollte darüber nachdenken das Kommentar in ein In-Code-Kommentar zu verwandeln. Die Kommentare eines Pull Requests sollen nur dem Zurechtfinden innerhalb des Pull Requests dienen.

Visuelle Unterstützung

Mit ein paar Screenshots der Frontend-Änderungen lässt sich mehr sagen als mit tausend Worten. Es ist einfacher Änderungen zu veranschaulichen, wenn man sie in Form eines Bildes sieht. Mit einem Video oder GIF lassen sich Änderungen im Ablauf oder Interaktion illustrieren.

Auch sollten die Designer in den Pull Request von Frontend-Änderungen aufgenommen werden. Designer sehen so visuelle Abweichungen oder Schreibfehler viel eher im Qualitätssicherungsprozess – dank Bildern.

Zusammenfassung

Die hier umrissenen Möglichkeiten sind lediglich einige der Wege, mit denen man Pull Requests für das ganze Unternehmen angenehmer machen kann. Beginnt man über Pull Requests als Produkt mit dem Autor als Verkäufer und dem Reviewer als Käufer zu denken, lassen sich Wege finden, wie man Pull Requests effektiver „verkaufen“ kann, sodass diese schneller akzeptiert werden.

Die hier vorgestellten Richtlinien sind lediglich Orientierungspunkte und keine festen Regeln. Betrachten Sie diesen Artikel als Anstoß und Ausgangspunkt, um Pull Requests effektiver zu gestalten. Vielleicht können wir auch helfen? Kontaktieren Sie uns.