Repository navigation
04 Relire le code
La revue sert à transmettre, pas à filtrer.
On croit souvent que la revue de code sert d'abord à attraper les bugs. Les études menées chez Microsoft et Google disent autre chose : la revue attrape quelques défauts, mais son premier effet est la diffusion de la connaissance. Après une revue, deux personnes savent pourquoi le code est écrit ainsi. Le jour où l'auteur part en vacances, l'équipe ne se retrouve pas démunie.
Cela change la façon de relire. Un relecteur qui cherche seulement des fautes produit des revues froides et des auteurs sur la défensive. Un relecteur qui cherche à comprendre pose des questions, et les questions trouvent plus de bugs que les accusations.
La qualité d'une revue dépend d'abord de ce que l'auteur présente.
- Une demande, un sujet. Une demande de fusion qui corrige un bug, renomme trois classes et met à jour une dépendance sera mal relue sur les trois sujets.
- Une description qui dit pourquoi. Le quoi se lit dans le code. Le pourquoi, seul l'auteur le connaît : le ticket d'origine, l'alternative écartée, le point sur lequel il a un doute.
- Une relecture de soi-même d'abord. Relire son propre diff dans l'outil de revue, avant de l'envoyer, élimine la moitié des commentaires évitables.
- Moins de 400 lignes. Au-delà, l'attention du relecteur chute fortement. Si le changement est forcément gros, on prévient et on propose de le parcourir ensemble.
L'ordre de lecture compte, parce que l'attention s'épuise.
- Le besoin. Lire la demande d'origine avant le code. Un code impeccable qui résout le mauvais problème reste un mauvais changement.
- Les échecs. Que se passe-t-il si l'appel réseau expire ? Si le message arrive deux fois ? Si la valeur est absente ? Si deux requêtes concurrentes modifient la même ligne ? C'est là que se cachent les incidents de demain.
- Les tests. Prouvent-ils le comportement, ou exécutent-ils simplement des lignes ? Un test qui ne peut pas échouer ne prouve rien.
- La lisibilité. Un collègue arrivé l'an prochain comprendra-t-il ce code sans l'auteur ?
- Le reste. Noms, style, petites améliorations. Utile, mais jamais bloquant.
Inspirées des Conventional Comments :
| Étiquette | Sens | Bloque la fusion ? |
|---|---|---|
| bloquant | Un défaut à corriger avant fusion | oui |
| question | Je ne comprends pas, explique-moi | tant qu'il n'y a pas de réponse |
| suggestion | Une idée, à toi de juger | non |
| détail | Sans importance | non |
| bravo | Ce qui est bien fait mérite d'être dit | non |
La dernière étiquette n'est pas une politesse. Signaler ce qui est réussi indique à l'auteur ce qu'il faut refaire, et à l'équipe ce qu'est un bon code chez nous.
On commente le code, jamais la personne. « Ce bloc ne gère pas le cas où la liste est vide » plutôt que « tu as oublié la liste vide ». La nuance paraît mince ; sur cent revues, elle fait la différence entre une équipe qui apprend et une équipe qui se protège.
Quand un échange dépasse trois allers-retours sur le même point, on arrête d'écrire et on se parle. Puis on note la conclusion dans la revue, pour la trace.
Une première réponse en moins d'une demi-journée ouvrée. Relire passe avant commencer une nouvelle tâche. La raison est mécanique : chaque heure d'attente pousse l'auteur à entamer autre chose, et un développeur qui jongle avec trois sujets ouverts les termine tous plus tard.
- Les demandes de fusion attendent plus d'une journée leur première relecture.
- Les revues se résument à « LGTM » en trente secondes sur 800 lignes.
- Ce sont toujours les deux mêmes personnes qui relisent tout.
- Les débats de style occupent plus de place que les questions de fond.
- Des développeurs découpent artificiellement leur travail pour éviter un relecteur redouté.
« La revue nous ralentit. » Elle ralentit une demande de fusion. Elle accélère l'équipe, parce qu'elle évite les bugs qui coûtent des jours et les zones de code que seule une personne comprend. Si la revue ralentit vraiment, regardez la taille des demandes et le délai de première réponse : c'est presque toujours là que ça coince.
« En binôme ou en mob programming, la revue est superflue. » Pour le code écrit à plusieurs, c'est souvent vrai : la relecture a eu lieu pendant l'écriture. Je garde alors une validation légère, qui vérifie surtout la description et les tests.
- Google, Engineering Practices: Code Review.
- Conventional Comments.
- Alberto Bacchelli, Christian Bird, « Expectations, Outcomes, and Challenges of Modern Code Review », ICSE 2013.
Engineering playbook · texte sous licence CC BY 4.0 · une objection ? ouvrez une issue
Les fondations
Décider et cadrer
Quand ça se complique
L'équipe
Modèles