Ik voer nu al meer dan tien jaar dagelijkse code-reviews uit. De voordelen van code reviews zijn legio: iemand controleert je werk op fouten, ze leren van je oplossing, en de samenwerking helpt om de algehele aanpak van de organisatie op het gebied van tooling en automatisering te verbeteren. Als je momenteel nog geen code reviews doet in je organisatie, begin er dan nu mee. Het zal van iedereen een betere ingenieur maken.
Veel mensen en organisaties hebben hun code review best practices gedeeld en wat de definitie van goede code reviews voor hen inhoudt. Gidsen van Google, het SmartBear team, en ingenieur Philipp Hauer zijn allemaal uitstekend leesvoer. Hieronder is mijn persoonlijke kijk op hoe goede code reviews eruit zien en hoe ze nog beter te maken op het niveau van het team en de organisatie. Dit is in de context van de tech omgeving waar ik heb gewerkt – momenteel bij Uber, en daarvoor bij Skype/Microsoft en Skyscanner.
Goede code reviews zijn de lat waar we allemaal naar zouden moeten streven. Ze omvatten algemene en eenvoudig te volgen best practices waarmee elk team aan de slag kan, terwijl ze zorgen voor kwalitatief hoogwaardige en nuttige beoordelingen voor de lange termijn.
Betere code reviews zijn waar ingenieurs blijven verbeteren hoe ze code reviews uitvoeren. Deze code reviews kijken naar de code verandering in de context van de codebase, van wie het aanvraagt en in welke situatie. Deze reviews passen hun aanpak aan op basis van de context en de situatie. Het doel is niet alleen een kwalitatief hoogwaardige review, maar ook om de ontwikkelaars en teams die de review aanvragen te helpen productiever te zijn.
Domeinen van de code review
Goede code reviews kijken naar de wijziging zelf en hoe deze in de codebase past. Ze kijken naar de duidelijkheid van de titel en beschrijving en het “waarom” van de wijziging. Ze gaan in op de juistheid van de code, testdekking, functionaliteitswijzigingen, en bevestigen dat ze de codeergidsen en best practices volgen. Ze wijzen op voor de hand liggende verbeteringen, zoals moeilijk te begrijpen code, onduidelijke namen, uitgecommentarieerde code, niet geteste code, of niet afgehandelde randgevallen. Ze zullen ook opmerken wanneer te veel wijzigingen in één review worden gepropt, en voorstellen om codewijzigingen enkelvoudig te houden of de wijziging op te splitsen in meer gerichte delen.
Betere code-reviews kijken naar de wijziging in de context van het grotere systeem, en controleren ook of wijzigingen gemakkelijk te onderhouden zijn. Ze kunnen vragen stellen over de noodzaak van de verandering of over de invloed ervan op andere delen van het systeem. Ze kijken naar geïntroduceerde abstracties en hoe deze passen in de bestaande software architectuur. Ze noteren opmerkingen over onderhoudbaarheid, zoals complexe logica die kan worden vereenvoudigd, het verbeteren van de teststructuur, het verwijderen van duplicaties, en andere mogelijke verbeteringen. Ingenieur Joel Kemp omschrijft goede code-reviews als een contextuele doorloop na een eerste, lichte doorloop.
Toon van de review
De toon van code-reviews kan het moreel binnen teams sterk beïnvloeden. Reviews met een harde toon dragen met hun microagressies bij aan het gevoel van een vijandige omgeving. Eigenwijs taalgebruik kan mensen defensief maken en verhitte discussies uitlokken. Tegelijkertijd kan een professionele en positieve toon bijdragen aan een meer inclusieve omgeving. Mensen in deze omgevingen staan open voor constructieve feedback en code reviews kunnen in plaats daarvan gezonde en levendige discussies op gang brengen.
Goede code reviews stellen open vragen in plaats van krachtige of opiniërende uitspraken te doen. Ze bieden alternatieven en mogelijke omwegen die beter zouden kunnen werken voor de situatie, zonder erop aan te dringen dat deze oplossingen de beste of enige manier zijn om verder te gaan. Deze beoordelingen gaan ervan uit dat de reviewer iets over het hoofd ziet en vragen om opheldering in plaats van correctie.
Betere code-reviews zijn ook empathisch. Ze weten dat de persoon die de code schrijft veel tijd en moeite heeft besteed aan deze verandering. Deze code-reviews zijn vriendelijk en bescheiden. Ze juichen mooie oplossingen toe en zijn all-round positief.
Wijzigingen goedkeuren vs. wijzigingen aanvragen
Als een reviewer klaar is met zijn review, kan hij deze als goedgekeurd markeren, de review blokkeren met wijzigingsverzoeken of geen specifieke status instellen, waardoor de review in de status “nog niet goedgekeurd” blijft staan. Hoe reviewers de goedkeur en wijzigingsverzoeken statussen gebruiken is veelzeggend voor de code reviews.
Goede code reviews keuren geen wijzigingen goed zolang er open vragen zijn. Ze maken echter wel duidelijk welke vragen of opmerkingen niet-belemmerend of onbelangrijk zijn, door ze duidelijk te markeren. Ze zijn expliciet bij het goedkeuren van een wijziging – bijvoorbeeld door het toevoegen van een duim omhoog commentaar zoals “ziet er goed uit!”. Sommige plaatsen gebruiken acroniemen zoals LGTM-deze werken ook, maar wees je ervan bewust dat nieuwkomers deze insider acroniemen verkeerd zouden kunnen interpreteren voor iets anders. Goede code-reviews zijn net zo expliciet als ze om een follow-up vragen, en gebruiken de code-review tool of teamafspraak om dit te communiceren.
Beter code-reviews zijn principieel streng, maar flexibel in de praktijk: soms worden bepaalde opmerkingen door de auteur beantwoord met een aparte, opvolgende codewijziging. Voor wijzigingen die urgenter zijn dan andere, proberen reviewers zich beschikbaar te stellen voor snellere reviews.
Van code reviews naar praten met elkaar
Code reviews worden meestal asynchroon en schriftelijk gedaan via een code review tool. Dit is meestal uit gemakzucht, om code-reviews op afstand mogelijk te maken, en om meerdere mensen in staat te stellen dezelfde codewijziging te beoordelen. Maar wanneer is het tijd om te stoppen met het gebruik van de tool, hoe goed die ook mag zijn, en te beginnen met het persoonlijk bespreken van de code?
Goede code reviews laten zoveel opmerkingen en vragen achter als nodig is. Als de revisie niet op alle vragen ingaat, zullen ze die ook noteren. Als het gesprek lang heen en weer gaat, zullen reviewers proberen om persoonlijk met de auteur te praten in plaats van meer tijd te verspillen aan het gebruik van de code review tool.
Beter code-reviewers zullen proactief contact opnemen met de persoon die de wijziging aanbrengt nadat ze een eerste pass op de code hebben gedaan en veel opmerkingen en vragen hebben. Deze mensen hebben geleerd dat ze op deze manier veel tijd, misverstanden, en harde gevoelens besparen. Het feit dat er veel commentaar op de code is, geeft aan dat er waarschijnlijk aan beide kanten een misverstand bestaat. Dit soort misverstanden kunnen gemakkelijker worden vastgesteld en opgelost door de dingen door te spreken.
Nitpicks
Nitpicks zijn onbelangrijke opmerkingen, waarbij de code zou kunnen worden samengevoegd zonder dat deze zelfs maar worden behandeld. Dit kunnen dingen zijn als variabele declaraties in alfabetische volgorde, unit tests die een bepaalde structuur volgen, of haakjes die op dezelfde regel staan.
Goede code reviews maken het duidelijk wanneer veranderingen onbelangrijke nitpicks zijn. Ze markeren dit soort opmerkingen meestal duidelijk, door er het voorvoegsel “nit:” aan toe te voegen. Te veel van deze opmerkingen kunnen frustrerend worden en de aandacht afleiden van de belangrijkere delen van de review, dus reviewers proberen hier niet te veel mee te doen.
Beter code reviews realiseren zich dat te veel pietluttigheden een teken zijn van gebrek aan tooling of een gebrek aan standaarden. Reviewers die deze vaak tegenkomen zullen kijken naar het oplossen van dit probleem buiten het code review proces. Bijvoorbeeld, veel van de veel voorkomende nitpick opmerkingen kunnen opgelost worden via geautomatiseerde linting. De opmerkingen die dat niet kunnen, kunnen meestal worden opgelost door het team te laten instemmen met bepaalde standaarden en deze te volgen – misschien zelfs te automatiseren.
Code Reviews voor nieuwkomers
Starten bij een nieuw bedrijf is voor de meeste mensen overweldigend. De codebase is nieuw, de programmeerstijl is anders dan voorheen, en mensen beoordelen je code heel anders. Dus moeten code-reviews vriendelijker zijn voor nieuwe starters, om ze te laten wennen aan de nieuwe omgeving, of moeten ze de lat net zo hoog houden als voor ieder ander?
Goede code-reviews gebruiken dezelfde kwaliteitslat en aanpak voor iedereen, ongeacht hun functie, niveau of wanneer ze bij het bedrijf zijn gekomen. In navolging van het bovenstaande hebben code-reviews een vriendelijke toon, vragen ze om wijzigingen waar nodig, en reiken ze de hand om met reviewers te praten als ze veel opmerkingen hebben.
Betere code-reviews besteden extra aandacht om de eerste paar reviews voor nieuwkomers een geweldige ervaring te laten zijn. De reviewers hebben begrip voor het feit dat de nieuwkomer misschien niet op de hoogte is van alle codeerrichtlijnen en misschien niet bekend is met delen van de code. Deze beoordelingen doen extra moeite om alternatieve benaderingen uit te leggen en naar gidsen te verwijzen. Ze zijn ook zeer positief van toon, en vieren de eerste veranderingen in de codebase die de auteur voorstelt.
Cross-Office, Cross-Time Zone Reviews
Code reviews worden moeilijker als de reviewers zich niet op dezelfde locatie bevinden. Ze worden vooral een uitdaging als de reviewers in heel verschillende tijdzones zitten. Ik heb in de loop der jaren mijn deel van deze reviews gehad, waarbij ik code heb aangepast die eigendom was van teams in de VS en Azië, terwijl ik in Europa werkte.
Goede code-reviews houden rekening met het verschil in tijdzone als ze kunnen. Reviewers streven ernaar de code te reviewen tijdens de overlappende werktijden tussen de kantoren. Voor reviews met veel commentaar zullen reviewers aanbieden om direct te chatten of een videogesprek te voeren om de wijzigingen door te spreken.
Beter code reviews merken op wanneer code reviews herhaaldelijk tegen tijdzoneproblemen aanlopen en zoeken naar een systematische oplossing, buiten het code review framework. Laten we zeggen dat een team uit Europa regelmatig een dienst wijzigt die code reviews uitlokt van de in de VS gevestigde eigenaar van deze dienst. De vraag op systeemniveau is waarom deze veranderingen zo vaak gebeuren. Worden de wijzigingen in de juiste codebase gedaan of moet een ander systeem worden gewijzigd? Zal de frequentie van de wijzigingen gelijk blijven of afnemen in de loop van de tijd? Ervan uitgaande dat de wijzigingen in de juiste codebase worden gedaan en de frequentie niet zal afnemen, kan de afhankelijkheid tussen kantoren op de een of andere manier worden doorbroken? Oplossingen voor dit soort problemen zijn vaak niet eenvoudig en kunnen refactoring, het creëren van nieuwe diensten/interfaces of tooling verbeteringen inhouden. Maar het oplossen van dergelijke afhankelijkheden maakt het leven van beide teams eenvoudiger en hun voortgang op de lange termijn efficiënter, waardoor de return on investment vaak indrukwekkend is.
Organisatorische ondersteuning
De manier waarop bedrijven en hun engineering-organisaties code-reviews benaderen, bepaalt voor een groot deel hoe efficiënt ze kunnen zijn. Organisaties die code-reviews als onbelangrijk en triviaal beschouwen, investeren er uiteindelijk weinig in om ze eenvoudiger te maken. In dergelijke culturen kan het verleidelijk zijn om code reviews gewoon helemaal af te schaffen. Engineers die pleiten voor betere code-reviews zouden zich geïsoleerd kunnen voelen, zonder steun van bovenaf en uiteindelijk opgeven. Het resultaat is een organisatie waar problemen zich blijven herhalen en zich blijven opstapelen.
Organisaties met goede code-reviews zorgen ervoor dat alle ingenieurs deelnemen aan het code-review proces – zelfs degenen die aan soloprojecten werken. Ze moedigen aan om de kwaliteits lat hoger te leggen, en teams faciliteren gezonde discussies over code review benaderingen, zowel op team- als op org-niveau. Deze bedrijven hebben vaak code review guides voor grotere codebases die ingenieurs geïnitieerd en geschreven hebben. Dergelijke organisaties erkennen dat het nakijken van code een groot deel van de tijd van ingenieurs in beslag neemt. Veel van deze bedrijven zullen code reviews toevoegen als verwachtingen aan de competenties van ontwikkelaars, en verwachten dat senior engineers een groter deel van hun tijd besteden aan het beoordelen van de code van anderen.
Organisaties met betere code reviews hebben harde regels: geen code mag in productie komen zonder code review – net zoals veranderingen in business logica niet in productie komen zonder geautomatiseerde tests. Deze organisaties hebben geleerd dat het niet de moeite waard is om de kantjes eraf te lopen; in plaats daarvan hebben ze processen voor versnelde reviews voor dringende gevallen. Deze organisaties investeren in de productiviteit van ontwikkelaars, onder andere door voortdurend te werken aan efficiëntere code reviews en verbeteringen in de tooling. Behulpzame engineering executives hoeven niet overtuigd te worden van de voordelen van code reviews en andere engineering best practices. In plaats daarvan ondersteunen ze initiatieven voor betere tooling of efficiëntere code review processen die uit teams komen.
Wanneer mensen te maken krijgen met reviews die vijandig aanvoelen, hebben ze het gevoel dat ze hun stem kunnen laten horen en steun krijgen van iedereen om het probleem op te lossen. Senior engineers en managers beschouwen code-reviews die niet aan de maat zijn net zo goed als een probleem als slordige code of slecht gedrag. Zowel engineers als engineeringmanagers voelen zich in staat om de manier waarop code wordt gereviewd te verbeteren.
Begin met goed, maak het beter
Goede code-reviews zijn al met veel goede inzet uitgevoerd. Ze beoordelen de wijziging zelf grondig, vermijden een opiniërende toon in hun commentaar en maken de kritiekpunten duidelijk. Ze houden een consistente lat aan, ongeacht wie de review aanvraagt en proberen cross-time zone reviews minder pijnlijk te maken door hier extra aandacht aan te besteden. Organisaties met goede reviews zorgen ervoor dat elke ontwikkelaar regelmatig code reviews ontvangt en uitvoert. Dit is al een hoge lat – maar als je hier komt, stop dan niet. Code reviews zijn een van de beste manieren om je vaardigheden te verbeteren, anderen te begeleiden, en te leren hoe je een efficiëntere communicator kunt zijn.
Ga naar betere code reviews door voortdurend te verbeteren op de details, maar begin ook te kijken naar veranderingen op een hoog niveau. Wees empathisch in de toon van commentaar en bedenk manieren buiten het code review proces om frequente pietluttigheden te elimineren. Maak code reviews extra gastvrij voor nieuwe starters en zoek naar systemische oplossingen voor pijnlijke cross-time zone reviews. Organisaties die vooruitstrevend zijn, stimuleren investeringen in tooling en procesverbeteringen om code reviews beter te maken en plukken daar meer de vruchten van.
—
Gergely is momenteel een engineering lead in Amsterdam. Deze blogpost verscheen oorspronkelijk op Gergely’s blog, The Pragmatic Engineer. Als je meer van Gergely wilt lezen, kun je je abonneren op zijn maandelijkse nieuwsbrief voor zijn artikelen over engineering, tech leiderschap en gedistribueerde systemen. Als je artikelen wilt bijdragen aan de Stack Overflow blog, stuur dan een e-mail naar [email protected].
Tags: bulletin, code review, engineering, software ontwikkeling