Best practices voor codebeoordeling

De auteur profiteren van een andere kijk op hun taak en code. Ze zullen vaak nieuwe trucs leren of een mogelijk optimalere manier ontdekken om een bepaald probleem op te lossen. Ze zullen ook vol vertrouwen hun wijzigingsset implementeren, wetende dat andere mensen de code hebben gecontroleerd op correctheid en het erover eens zijn dat alles in orde is.

De recensent profiteren van het zien van verschillende benaderingen van probleemoplossing in actie. Ze zullen ook hun vaardigheid in het lezen van code verbeteren, wat erg belangrijk is wanneer ze bijvoorbeeld in een bibliotheek duiken die geëvalueerd wordt voor gebruik in een project. Code review is net zo goed een leermoment voor de reviewer als voor de auteur: zij kunnen ook nieuwe trucs leren.

De team als geheel profiteert, omdat het beoordelen van een oplossing voor een bepaald probleem vereist dat je het probleem op zijn minst op een hoog abstractieniveau begrijpt. Dit helpt bij het afbreken van onbedoelde kennissilo's die in een team kunnen ontstaan. Het verhoogt ook de "busfactor": omdat ten minste twee mensen (bij voorkeur meer) op de hoogte zijn van een bepaalde wijziging, is de kans kleiner dat niemand in het team weet hoe een module moet worden bijgewerkt of waarom een bepaalde bug zich voordoet.

De klant profiteert van snel en met vertrouwen uitgerolde wijzigingen en oplossingen. Samen met andere best practices (zoals goede testdekking, CI/CD, staging-omgevingen, enz.) zorgen code-reviews er ook voor dat wat wordt ingezet veilig en gezond is en voldoet aan de vereisten zoals gespecificeerd.

Intentie en gebruik van deze richtlijnen

Onthoud dat deze suggesties bovenal bedoeld zijn om een omgeving te creëren die bevorderlijk is voor ambitieuze en efficiënte probleemoplossing, terwijl er tegelijkertijd een vangnet wordt gecreëerd en het vertrouwen en de transparantie van elk teamlid worden gestimuleerd.

Hoewel het sterk aanbevolen wordt dat een team zich aan deze richtlijnen houdt, zijn ze niet bedoeld als harde en snelle regels. Dit raamwerk is ook niet bedoeld als een "proces" dat precies gevolgd moet worden, omdat rigide processen de neiging hebben om de snelheid te verlagen en verspilling te bevorderen.

Je bent meer dan welkom om verder te bouwen op deze richtlijnen binnen je team. Onthoud echter dat als ontwikkelaars van het ene team naar het andere gaan, ze verwachten dat de codebeoordeling in elk team waar ze bij komen nog steeds gebaseerd is op dit document. Houd alle aanvullende regels gedocumenteerd en draag verbeteringen die uitzonderlijk goed hebben gewerkt bij aan dit document.

Verantwoordelijkheden rond code review

Iedereen in het team heeft bepaalde verantwoordelijkheden met betrekking tot code review. Hieronder worden bepaalde do's en don'ts van code review uiteengezet per rol in het proces.

Projectleider

• DO ervoor zorgen dat je repositories goed geconfigureerd zijn (bijvoorbeeld samenvoegingen naar je productie-facing branch zijn niet toegestaan zonder tenminste één goedkeurende review).
• DO Zorg ervoor dat je team deze werkwijzen begrijpt en toepast, en werk actief aan het bevorderen van begrip voor waarom we dingen op een bepaalde manier doen.
• DO let op situaties met een gelijkspel, waarbij tegengestelde meningen niet kunnen worden opgelost: als technisch leider van je team is het jouw verantwoordelijkheid om in zulke gevallen de meest relevante oplossing te kiezen en het werk voortgang te laten vinden.
• Echter, NIET DOEN gebruik projectleiderschap als een bot instrument. NIET DOEN "pull rank". DO Beoordeel en bekritiseer je oplossingen net zo graag als je dat op iemands werk doet.
• OVERWEG het toevoegen van een GitHub integratie aan het Slack kanaal van je team. Het kan handig zijn om reviewverzoeken beter op de radar van reviewers te krijgen, maar afhankelijk van het totale volume in je kanaal kan dit wel of niet geschikt zijn voor je team.

Teamlid

• Doe mee aan code-reviews. Het is niet acceptabel om code niet te reviewen.
• Vergeet niet om je code te reviewen: je teamgenoten rekenen op je om vooruitgang te boeken met hun werk!
• Als je een bepaalde recensie absoluut niet kunt doen, DO communiceer het duidelijk en open.
• Echter, NIET DOEN aannemen dat je een bepaalde review niet kunt doen omdat je die module/kant van het systeem/business logic specs niet kent. Code review is een belangrijke leermogelijkheid.
• Als je het gevoel hebt dat je ergens niet genoeg over weet om een recensie te schrijven, DO Vraag de auteur ernaar: zij zullen graag uitleggen wat de wijzigingen zouden moeten doen.
• NIET DOEN Weiger beoordelingen op basis van ervaringsniveau (de jouwe of van de auteur).
• DO Probeer minstens zoveel PR's te beoordelen als je produceert. In het ideale geval is de verhouding tussen gegeven beoordelingen en vereiste beoordelingen meer dan 1 (vooral bij grotere teams).

Auteur

• DO begrijpen dat het jouw verantwoordelijkheid is om je code te laten nakijken - je team kan proactief op zoek zijn naar pull requests om na te kijken, maar dat hoeft niet.
• NIET DOEN altijd reviews toewijzen/vragen van dezelfde teamleden - u zult meer profiteren van een gevarieerde groep reviewers (en omgekeerd zullen meer ontwikkelaars profiteren van het reviewen van uw code)
• NIET DOEN iemand uitsluiten van review op basis van ervaring. Junior ontwikkelaars hebben baat bij het reviewen van code. Senior ontwikkelaars hebben baat bij het reviewen van code. Zoals in het voorwoord van dit document staat, iedereen baat heeft bij het beoordelen van code.
• OVERWEG een randomizer gebruiken om je reviewers te selecteren. Bijvoorbeeld in Ruby, %w[teamgenoot1 teamgenoot2 teamgenoot3].sample kan wonderen doen.
• DO wijs minstens twee reviewers toe aan je pull requests, tenzij het absoluut onmogelijk is. Op die manier profiteren meer mensen van het proces (en met drie mensen is het moeilijker om tot een gelijkspel te komen).
• DO Wees responsief in je pull requests. Hoewel je je flow niet moet onderbreken om direct te reageren op commentaar, zorg er wel voor dat je tijdig reageert - anders zullen je PR's voor onbepaalde tijd blijven hangen in code review.
• DO neem een open houding aan. Ga er altijd van uit dat je recensent met de beste bedoelingen probeert te helpen. Leg je logica uit, ga in op de argumenten van je recensent en beantwoord hun vragen.
• DO beleefd zijn. Misverstanden komen voor, maar ze hoeven niet uit de hand te lopen en de sfeer in het team te verstoren.
• DO wees eerlijk. Als je denkt dat dit de beste oplossing is, zeg dat dan en geef je argumenten. Als je ervan overtuigd raakt dat de suggesties van je reviewer beter zijn dan wat jij hebt geproduceerd, vertel het hen dan. Als u denkt dat een "beste van twee werelden" oplossing kan worden geproduceerd met zowel uw ideeën als die van uw reviewer, stel die dan aan hen voor. Werk uiteindelijk naar een consensus toe in je pull requests.
• DO Laat het oplossen van hun opmerkingen over aan je reviewer - los ze niet zomaar op omdat je ervan overtuigd bent dat het nu in orde is.
• DO Leg je taak, je redenering en andere vereisten actief uit aan je beoordelaars. Het is prima om het niet te weten - het is niet acceptabel om kennis achter te houden.
• NIET DOEN ervan uitgaan dat je alles weet - we zijn allemaal geweldige specialisten, maar het is belangrijk om een zekere mate van nederigheid mee te nemen naar je werk.
• DO Wees de eerste beoordelaar van je code. Draag een reviewer's hoed en scan de code zorgvuldig zoals je zou doen voor de persoon die je het meest niet mag. Identificeer en elimineer de meest voor de hand liggende dingen, zoals lege regels, restjes of ontbrekende specificaties. Sla niets over - het wordt waarschijnlijk toch wel opgemerkt. Verspil de tijd van de reviewers niet!
• DO Beschrijf je pull request grondig. Een beschrijving is goed als de reviewer niet verrast wordt door iets tijdens het lezen van de code. Vergeet niet dat hij je gedachten niet kan lezen. Daarom is het belangrijk om dingen te beschrijven die niet voor de hand liggen, belangrijke beslissingen met de reden of alle nieuwe classes en bestanden.
• OVERWEG met behulp van het pull request-sjabloon. Als je Github gebruikt, voeg het dan toe aan je repository onder .github/pull_request_template.md. Het moedigt alle teamleden aan om hun pull requests te beschrijven. Het is ook veel gemakkelijker om te schrijven als je het beschrijvingsveld gevuld hebt met een sjabloon. Hier vind je een sjabloon dat we gebruiken in een van onze projecten https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Auteur

• DO begrijpen dat het jouw verantwoordelijkheid is om je codeherziening - Je team is misschien proactief op zoek naar pull requests om te beoordelen, maar dat hoeft niet.
• NIET DOEN altijd beoordelingen toewijzen/vragen van dezelfde code reviewers - u zult meer profiteren van een gevarieerde groep reviewers (en omgekeerd zullen meer ontwikkelaars profiteren van het reviewen van uw code)
• NIET DOEN iemand uitsluiten van beoordeling op basis van ervaring. Junior ontwikkelaars hebben baat bij het uitvoeren van code beoordelingen. Senior ontwikkelaars profiteren van het uitvoeren van code beoordelingen. Zoals vermeld in het voorwoord van dit document, iedereen voordelen van het uitvoeren van code beoordelingen.

Recensent

• DO gebruik de taal van suggesties in plaats van eisen. In plaats van te zeggen "Je moet codekwaliteit verbeteren door in plaats daarvan X te doen"zeggen "Heb je overwogen om codekwaliteit door X te doen?"
• DO leg je suggesties uit. "Ik denk dat X hier beter is omdat het helpt in kennisoverdracht en codekwaliteit verbeteren."
• Zelfs als je suggestie afkomstig is van objectieve bronnen (bijv. codestijl richtlijnen), DO vraag de auteur iets te doen in plaats van hem te vertellen iets te doen. "Houd alle widgets frobnicated volgens onze codestijl gids - [link]"
• NIET DOEN Ga ervan uit dat je alles weet. "Ik heb begrepen dat deze widget nooit mag bevriezen, en onder deze omstandigheden zal dat wel gebeuren - is dit een uitzondering waarvoor een codeherziening?"
• DO gebruik inclusieve taal. "Ik denk dat we in de toekomst beter af zouden zijn als we dit zo zouden bouwen. Wat vind je hiervan? betere code review suggestie?" en "Misschien moeten we hier X gebruiken voor een effectieve code review?"
• DO wees prompt in het doen van uw code beoordelingen. Je moet je flow niet onderbreken om ze te doen, maar probeer de lus zo strak mogelijk te houden. Sommige mensen doen ze graag aan het begin of het einde van hun werkdag, als "warming-up" of "cooldown".

Houd er rekening mee dat deze trefwoorden zijn ingevoegd op een manier die de context en samenhang van de tekst intact houdt. Als je ze op een specifieke plaats wilt hebben, geef dat dan aan.