16. La revue de code : élargir le regard
Pourquoi ce chapitre existe
La revue de code est trop souvent réduite à une vérification de style, à une porte d'approbation ou à une démonstration de compétence. Dans ces rôles, elle ajoute du délai et encourage des commentaires de préférence. Sa valeur réelle est différente : créer un moment où une personne qui n'a pas produit le changement confronte l'intention, les hypothèses, les effets de bord et les preuves disponibles.
Une bonne revue ne cherche pas un second auteur. Elle apporte une perspective distincte et laisse le système plus compréhensible qu'avant le changement.
Les idées essentielles
- Le code n'est qu'une partie de l'objet revu : contexte, tests, contrat, plan de déploiement et observabilité peuvent être essentiels.
- Le relecteur est responsable d'exprimer le niveau de certitude de ses commentaires, pas d'imposer ses goûts.
- Une approbation signifie que le risque a été examiné à un niveau adapté ; elle ne garantit pas l'absence de défaut.
- Le temps de revue est une boucle de feedback : une attente longue réduit la qualité et favorise les gros lots.
Relire à trois niveaux
Une revue utile commence par le résultat attendu, puis descend progressivement vers l'implémentation.
| Niveau | Questions principales |
|---|---|
| Intention | Quel problème est résolu ? Qu'est-ce qui reste vrai ? Quel impact est accepté ? |
| Conception | Les frontières, contrats, erreurs et données rendent-ils la solution évolutive ? |
| Exécution | Le code exprime-t-il cette conception ? Les tests et la livraison produisent-ils les preuves attendues ? |
Commencer directement ligne par ligne fait perdre le contexte et récompense les détails les plus visibles. Une PR devrait donc expliquer en quelques lignes le comportement, le risque, les décisions inhabituelles et la manière de vérifier le résultat. Cette information n'est pas un formulaire ; elle économise des allers-retours et permet au relecteur de repérer ce que le diff ne montre pas.
Commenter avec précision
Un commentaire est plus utile lorsqu'il dit ce qui est observé et pourquoi cela compte : « Si cet événement est rejoué, cette écriture peut créer un second remboursement ; avons-nous une clé d'idempotence ? » est actionnable. « Ce code est dangereux » ne l'est pas. Distinguer une question, une suggestion, un blocage fondé sur un risque et une préférence stylistique évite aussi de donner au même poids des remarques très différentes.
Une décision à fort rayon d'action, une ambiguïté métier ou une divergence de conception peut nécessiter dix minutes de discussion. Continuer à échanger des messages pour préserver le rituel de la PR est rarement efficace. La décision obtenue doit ensuite être résumée là où elle sera retrouvée.
Anti-patterns
Corriger le style avant de comprendre le changement
Le formatage et les conventions répétitives doivent être automatisés. Les imposer manuellement occupe l'attention qui devrait chercher les invariants cassés, les dépendances non observées et les conséquences de production.
Utiliser l'approbation comme transfert de responsabilité
Un auteur reste responsable de comprendre son changement ; un relecteur reste responsable de la qualité de son regard. L'approbation n'efface ni l'un ni l'autre, et ne doit jamais servir à rendre une personne coupable après incident.
Exiger la même profondeur pour tous les changements
Une faute de frappe et une migration irréversible ne demandent pas le même contexte ni les mêmes compétences. Le risque guide le nombre de regards, l'expertise requise et la nécessité d'une revue de plan avant le code.
Bonnes pratiques
Préparer une revue navigable
Garder le diff centré sur une intention, séparer les refactorings mécaniques, lier les décisions et fournir les commandes ou scénarios de vérification. Une revue navigable réduit la charge cognitive et rend possible un véritable contrôle de fond.
Faire de la revue un apprentissage réciproque
Un commentaire explique le raisonnement plutôt que seulement le correctif attendu. L'auteur fournit le contexte manquant sans se justifier. Avec le temps, les motifs récurrents deviennent des tests, des règles d'analyse ou des chapitres de handbook — pas une liste infinie de remarques humaines.
Checklist — La revue apporte-t-elle une preuve nouvelle ?
- Le lecteur comprend-il le comportement, les invariants et le risque avant de lire le diff ?
- Les tests répondent-ils aux comportements importants plutôt qu'aux seuls détails d'implémentation ?
- Les contrats, données, erreurs et modes de déploiement affectés ont-ils été considérés ?
- Les commentaires distinguent-ils blocage, question, suggestion et préférence ?
- La profondeur de revue est-elle proportionnée à l'impact ?
- Les décisions issues de la discussion seront-elles retrouvables plus tard ?
À retenir
La revue de code est une pratique de découverte collective. Elle devient précieuse lorsqu'elle élargit le regard au-delà du diff, rend les hypothèses contestables et transforme les apprentissages récurrents en améliorations du système de travail.