Afspraken voor code review op afstand

Code review op afstand werkt als pull requests klein zijn, reviewers binnen een werkdag reageren en de pipeline alles controleert wat een machine kan controleren. De reviewer houdt dan tijd over voor het ontwerp en voor de vraag of de code doet wat het ticket vraagt. Schrijf die afspraken op en zet ze in de repository, zodat een nieuwe developer ze vanaf de eerste dag kent.

Waarom review op afstand anders werkt

Op kantoor loop je even naar iemand toe. In een remote team is de pull request vaak het enige gesprek over de code, en een vraag in een reviewcomment die pas de volgende ochtend antwoord krijgt, kost een dag. Daarom wegen de grootte van een pull request en de reactietijd zwaarder dan op kantoor.

De review is ook de plek waar een nieuwe developer leert hoe jullie code schrijven. Wat daar staat, blijft bewaard, dus schrijf je comments zo dat iemand ze over een halfjaar nog begrijpt.

Kleine pull requests

Een kleine pull request krijgt sneller een review, en een betere. De code review-richtlijnen van Google noemen 100 regels meestal een redelijke grootte en 1000 regels meestal te groot. Ook het aantal bestanden telt: 200 regels in één bestand kan prima zijn, verspreid over 50 bestanden meestal niet.

Zet refactors en gedragswijzigingen altijd in aparte pull requests. Bij de refactor ziet de reviewer dan snel dat er niets verandert, en bij de wijziging ziet hij precies wat er verandert. Werk dat nog niet af is, kun je achter een feature flag mergen, zodat niemand een week op één grote branch zit.

Reageren binnen een werkdag

Google noemt één werkdag de maximale tijd om op een reviewverzoek te reageren. Voor een remote team zou ik strakker zijn. Onze developers werken vanuit Servië, in dezelfde tijdzone als Nederland, dus binnen een paar uur reageren is haalbaar.

Wat daarbij helpt:

• Een vast moment voor reviews, bijvoorbeeld aan het begin van de dag en na de lunch, voordat je aan nieuw werk begint.
• Vaste reviewers per deel van de code. Op GitHub doe je dat met een CODEOWNERS-bestand, waarna codeowners automatisch een reviewverzoek krijgen (behalve bij draft pull requests).
• Een regel op de main-branch die een goedkeuring van een codeowner verplicht maakt.
• Een afspraak voor een pull request die blijft liggen: na een halve dag noem je hem in het teamkanaal.

Wil je vroeg feedback op een aanpak, open dan een draft pull request en vraag er gericht om. Dat scheelt een ronde als de aanpak niet blijkt te kloppen.

Wat de pipeline controleert

Een reviewer hoort geen comments te schrijven over iets wat een tool had kunnen vinden. Laat de pipeline vóór de review draaien en maak deze checks verplicht:

• formattering en linting
• typecontrole en de build
• unit- en integratietests
• een scan op kwetsbare dependencies
• een scan op secrets in de code

Komt dezelfde opmerking steeds terug in reviews, maak er dan een regel in de linter van, zodat niemand hem nog hoeft te typen.

Onze developers gebruiken elke dag AI-codeertools zoals Claude Code. Gegenereerde code gaat door dezelfde pipeline en dezelfde review als andere code, en de auteur moet elke regel kunnen uitleggen. Een AI-reviewtool mag een eerste ronde doen, maar de goedkeuring komt van een mens. Welke afspraken je daarover maakt, staat in AI-codeertools in een remote team.

Waar de reviewer op let

Voor de reviewer blijft het werk over dat een tool niet kan doen:

• Doet de code wat het ticket vraagt, en klopt het met de acceptatiecriteria?
• Past de oplossing bij de architectuur, of komt er een tweede manier bij om hetzelfde te doen?
• Testen de tests het gedrag, of alleen de implementatie?
• Controleert elk nieuw endpoint of de gebruiker bij deze data mag?
• Wat gebeurt er als een externe call faalt of een migratie halverwege stopt?
• Kan een collega dit over een halfjaar nog lezen?

Voor de securityvragen is de OWASP Top 10 een goede basis voor je checklist.

Toon in geschreven feedback

Op schrift klinkt alles strenger dan je het bedoelt. In een remote team schrijf je bovendien vaak in het Engels, ook als dat voor niemand de moedertaal is. Een paar afspraken helpen:

• Stel een vraag in plaats van een oordeel. "Wat gebeurt hier als de lijst leeg is?" komt beter aan dan "Dit gaat mis."
• Geef aan hoe zwaar een opmerking weegt, bijvoorbeeld met "nit:" voor details en "blocking:" voor wat echt moet.
• Leg uit waarom, en stel waar het kan concrete code voor.
• Gaat een discussie meer dan twee rondes heen en weer, pak dan tien minuten een call en zet de uitkomst in de pull request.

Zet deze afspraken in een CONTRIBUTING-bestand en maak een template voor pull requests met wat er verandert, waarom, en hoe je het test. Hoe onze developers in jouw team en jouw reviewproces instromen, staat bij onze werkwijze.

Bronnen

• Google Engineering Practices: Speed of Code Reviews
• Google Engineering Practices: Small CLs
• GitHub Docs: About code owners