Conduire une revue de code constructive pas-à-pas

La revue de code est l’un des rituels les plus puissants en ingénierie logicielle, et l’un des plus mal exécutés. Bien menée, elle élève la qualité du code, transfère la connaissance dans l’équipe, et crée un effet de filet de sécurité collectif. Mal menée, elle braque les juniors, ralentit les releases, et installe un climat de défense où plus personne ne propose de changement ambitieux. Ce tutoriel décrit un protocole en sept étapes pour relecteurs et auteurs, inspiré des pratiques publiques de Google et des recherches de Microsoft sur la revue de code moderne.

Article principal : Soft-skills indispensables aux métiers de l’IT en 2026. Cet article fait partie d’une série sur les compétences comportementales en ingénierie.

Prérequis

• Avoir déjà ouvert ou relu au moins une pull request
• Accès à un dépôt GitHub, GitLab ou équivalent où des PR sont en cours
• Connaissance de base de Git (git diff, git log, git checkout)
• Un éditeur ou IDE capable d’ouvrir le code source du projet
• Niveau attendu : développeur junior à senior
• Temps estimé pour internaliser le protocole : 60 minutes pour la lecture, plusieurs semaines de pratique

Étape 1 — Comprendre ce qu’une revue de code est censée produire

Beaucoup d’équipes pratiquent la revue de code sans avoir explicitement aligné les attentes. Le résultat : un relecteur cherche les bugs, un autre traque le style, un troisième ne fait que valider l’intention. La PR avance ou recule selon qui ouvre l’onglet en premier. Avant tout protocole, il faut nommer les objectifs.

L’étude de Christian Bird et Alberto Bacchelli chez Microsoft, publiée à ICSE 2013 sous le titre Expectations, Outcomes, and Challenges of Modern Code Review, a montré que les développeurs s’attendent à ce que la revue détecte des bugs, mais qu’en pratique elle apporte plus de bénéfices côté transfert de connaissance, conscience d’équipe, et émergence d’alternatives de conception. Autrement dit, la revue est avant tout un outil de communication, secondairement un filet anti-bug.

Cette lecture change l’attitude du relecteur : son rôle n’est pas de « valider » ou « rejeter », c’est d’aider l’auteur à livrer une meilleure version du même changement, et de comprendre lui-même le code pour pouvoir intervenir dessus plus tard. La revue devient un dialogue, pas un examen. Tout le reste du protocole en découle.

Étape 2 — Lire la description avant le diff

Le piège du relecteur pressé est d’aller directement à l’onglet « Files changed » et de juger ligne par ligne. Cette habitude conduit à donner des avis hors-sujet : on commente une variable mal nommée alors que le vrai problème est que la solution choisie est inadaptée au problème.

La discipline est inverse : lire d’abord la description complète, le ticket lié, et la conversation existante sur la PR. Si la description ne dit pas pourquoi le changement est fait, le premier commentaire du relecteur doit être une demande de contexte, pas un commentaire de code. Cela paraît contre-intuitif, mais c’est ce qui économise le plus de temps à l’auteur — il évite de discuter ligne par ligne sur un code qu’il faudra peut-être réécrire entièrement.

Pour matérialiser cette discipline sur sa propre machine, ouvrir la PR via la commande GitHub CLI :

gh pr view 2841 --comments

Cette commande affiche dans le terminal le titre, la description, et tous les commentaires existants, sans encore montrer le diff. C’est exactement le contexte à charger en mémoire avant la lecture du code. La sortie attendue est un bloc structuré avec en-tête, body, puis fil des commentaires triés chronologiquement. Si la description tient en deux lignes vides ou ne contient qu’un lien vers Jira sans résumé, le premier commentaire à laisser est : « peux-tu résumer le pourquoi en 3 phrases dans la description ? ».

Étape 3 — Faire un premier passage en survol

Le deuxième passage est un survol, pas une lecture détaillée. Il s’agit d’identifier la structure globale du changement avant d’entrer dans les lignes. Concrètement, regarder la liste des fichiers modifiés et noter mentalement : combien de fichiers ? Dans quels modules ? Y a-t-il des fichiers de migration, de configuration, de tests ? La proportion code/tests est-elle raisonnable ?

Cette vue d’ensemble révèle parfois des problèmes structurels qu’on ne verrait pas en lisant ligne par ligne. Par exemple, si la PR modifie 30 fichiers dans 7 modules différents, on a probablement affaire à un changement qui aurait dû être découpé. Selon les recommandations Google, environ 100 lignes est une taille de changelist raisonnable et 1000 lignes est généralement trop. Un autre signal d’alerte : une PR qui prétend corriger un bug mais ne contient aucun test associé. Soit le bug n’est pas testable, soit l’auteur n’a pas pris le temps — dans les deux cas, c’est un point à clarifier avant de continuer.

La commande utile pour ce survol :

gh pr diff 2841 --name-only

La liste des fichiers tient sur une dizaine de lignes pour une PR bien découpée. Si elle dépasse trente lignes, on peut directement laisser un commentaire de cadrage avant même de lire le code : « cette PR touche 47 fichiers dans 8 modules, peux-tu la découper en deux ou trois ? ». Cette intervention précoce évite à l’auteur de défendre un travail qui partira au refactor de toute façon.

Étape 4 — Lecture détaillée avec un cadre mental clair

Pour le passage détaillé, il faut tenir en tête un cadre simple. Une heuristique répandue, parfois résumée par le sigle CARDIO, regroupe six dimensions de relecture : Correctness (le code fait-il ce qu’il prétend ?), Architecture (la solution s’intègre-t-elle bien ?), Readability (un autre dev comprend-il sans contexte ?), Documentation (les commentaires et docs sont-ils suffisants ?), Imports (les dépendances ajoutées sont-elles justifiées ?), Outliers (y a-t-il des cas limites non testés ?). On ne donne pas un score sur six ; on parcourt mentalement chaque dimension pour ne pas en oublier une.

L’erreur classique est de se concentrer uniquement sur la readability (style, noms de variables) parce que c’est le plus facile à voir, et de négliger l’architecture (la solution est-elle au bon niveau d’abstraction ?). Le commentaire qui apporte le plus de valeur est celui qui pointe une décision de conception sous-optimale. C’est aussi le plus difficile à formuler sans braquer l’auteur, ce qui nous amène à l’étape suivante.

En pratique, ouvrir un éditeur sur la branche pour voir le code en contexte vrai, pas seulement le diff :

gh pr checkout 2841
code .   # ou idea . / vim .

La première commande clone localement la branche de la PR et bascule dessus. La seconde ouvre le projet dans son éditeur. À ce stade on peut naviguer dans les fichiers complets, voir comment le code modifié interagit avec ses voisins, et tester en local si nécessaire. Cette inspection en contexte attrape des problèmes invisibles dans la fenêtre de diff GitHub : une fonction qui en dupliquait une autre déjà présente trois fichiers plus loin, par exemple.

Étape 5 — Formuler un commentaire qui ne braque pas

C’est l’étape la plus difficile. Un même fait peut être formulé d’une manière qui fait progresser l’auteur, ou d’une manière qui le ferme à toute remarque. La différence ne tient ni au sujet ni au fond : elle tient à la forme.

Trois principes

1. Commenter le code, pas la personne. « Cette fonction est mal écrite » devient « cette fonction pourrait gagner en lisibilité si on extrayait la condition en variable nommée ». La première formulation attaque l’auteur ; la seconde décrit un changement.

2. Expliquer le pourquoi, pas seulement le quoi. « Renomme `x` en `userCount` » devient « `x` rend la lecture difficile parce qu’on doit suivre son cheminement sur 30 lignes pour deviner le sens ; un nom comme `userCount` rendrait la fonction auto-documentée ». Le pourquoi permet à l’auteur d’apprendre la règle, pas juste d’appliquer la correction.

3. Distinguer les niveaux d’attente. Tous les commentaires ne se valent pas. Certains bloquent le merge, d’autres sont des suggestions. La convention conventional comments (conventionalcomments.org) propose des préfixes explicites : nit: (détail mineur), suggestion: (proposition non bloquante), question: (demande d’éclaircissement), issue: (problème à corriger), blocking: (bloque le merge). Cette convention retire l’ambiguïté et permet à l’auteur de prioriser.

Exemples concrets

Comparons trois formulations sur le même point technique :

❌ "C'est faux, ça va lever une exception."

⚠️ "Tu as oublié de gérer le cas null."

✅ "issue: si `user` est null (cas observé en prod via #2103),
    cette ligne va lever une NullPointerException. On peut le gérer
    avec un Optional ou un check explicite — je penche pour Optional
    parce que c'est déjà le pattern utilisé dans `UserService`."

La troisième formulation est plus longue mais elle apporte trois choses : la preuve du problème (référence #2103), la solution suggérée, et la justification du choix. L’auteur peut accepter, contester avec arguments, ou proposer une autre voie. Le dialogue est ouvert.

Étape 6 — Côté auteur : recevoir et répondre aux commentaires

Le protocole côté auteur est tout aussi important que celui du relecteur. Une PR mal accueillie côté auteur transforme la revue en bataille, peu importe la qualité du commentaire initial.

Trier les commentaires avant de répondre

Quand une PR reçoit dix commentaires d’un coup, la tentation est de répondre à chaud, dans l’ordre, à chacun. C’est inefficace. La discipline : lire tous les commentaires d’abord, les classer mentalement en trois catégories — bloquants, légitimes mais discutables, désaccord — puis répondre par ordre d’impact, pas d’arrivée.

Pour les bloquants évidents (« le test fail »), corriger sans débat. Pour les légitimes mais discutables, soit on accepte avec explication courte, soit on propose une alternative argumentée. Pour les désaccords sur le fond (architecture, choix de design), on prend trente minutes pour formuler une réponse posée. Jamais répondre à chaud sur un point d’architecture — la défense émotionnelle est garantie de mauvaise réception.

Le syndrome du « ça marche, ne touche pas »

Beaucoup d’auteurs se braquent sur l’argument « ça fonctionne, tes tests passent, donc le code est bon ». C’est faux. Un code peut fonctionner et être impossible à maintenir, ou ouvrir une faille de sécurité dans six mois quand un nouveau chemin d’appel sera ajouté. La revue de code regarde aussi ces dimensions, pas seulement la fonctionnalité immédiate.

Si on n’arrive pas à expliquer la valeur d’un commentaire à un auteur résistant, on peut tester avec la question miroir : « si demain je veux ajouter une fonctionnalité dans cette zone, quel travail mon successeur devra-t-il refaire à cause de ce choix ? ». Cette question déplace le débat du présent (« ça marche ») au futur (« ça va vieillir comment ») et résout en général le désaccord.

Marquer chaque commentaire comme résolu

Lorsqu’on traite un commentaire — qu’on accepte ou qu’on argumente — on le marque comme résolu sur GitHub avec un message bref : « fixé en abc1234 », ou « j’ai gardé Optional pour la raison X, voir thread ». Cette discipline laisse au relecteur une vue claire de ce qu’il reste à examiner. Une PR avec 30 commentaires non marqués est ingérable côté relecteur ; la même PR avec 28 résolus et 2 ouverts se finalise en cinq minutes.

Étape 7 — Boucler la revue : valider ou demander un nouveau passage

La dernière étape est la décision finale du relecteur. Trois options : approve (le code est prêt à être mergé), request changes (un point bloquant reste ouvert), comment (remarques sans bloquer ni valider, utile quand on n’est pas le code owner principal).

L’erreur classique est d’utiliser request changes pour des nits de style, ce qui bloque le merge artificiellement. La bonne pratique : request changes uniquement pour des problèmes de correctness, sécurité, ou architecture. Pour les détails de style, approve avec un commentaire « voici quelques nits à traiter dans une autre PR ou avant le merge selon ton choix ».

Une fois la décision prise, l’envoyer en bloc plutôt qu’en plusieurs commentaires séparés. GitHub permet de regrouper tous les commentaires en attente dans une seule revue avec la fonction « Start a review ». L’auteur reçoit une notification unique avec tous les points, plutôt qu’un déluge de notifications individuelles. Cette pratique réduit la charge cognitive de l’auteur et augmente la probabilité qu’il traite les commentaires sérieusement.

La commande terminal équivalente avec GitHub CLI :

gh pr review 2841 --approve --body "LGTM côté logique. 2 nits non bloquants en commentaires."
gh pr review 2841 --request-changes --body "Voir le commentaire bloquant sur la gestion du null."

Le premier exemple approuve avec un message synthétique. Le second demande des changements en pointant le commentaire bloquant. Dans les deux cas, l’auteur sait précisément ce qui est attendu et peut agir sans relire trois fois la conversation.

Erreurs fréquentes

Tutoriels associés

• Rédiger une description de pull request claire pas-à-pas — le pendant côté auteur, à lire avant ce tutoriel.
• Animer un stand-up et une rétrospective d’équipe pas-à-pas — pour communiquer en équipe sur les revues bloquantes.

Pour aller plus loin

• 🔝 Retour à l’article principal : Soft-skills indispensables aux métiers de l’IT en 2026
• Google Engineering Practices — Code Review
• The Standard of Code Review (Google)
• Bird & Bacchelli, Expectations, Outcomes, and Challenges of Modern Code Review, ICSE 2013
• Conventional Comments — préfixes pour clarifier l’intention
• GitHub CLI — gh pr review

Questions fréquentes

Combien de temps consacrer à une revue ?

L’ordre de grandeur observé dans plusieurs études est de 200 à 400 lignes de code par heure pour une revue de qualité. Au-delà, la concentration baisse et les défauts passent inaperçus. Si la PR fait 800 lignes, prévoir deux sessions séparées plutôt qu’une seule session de deux heures.

Faut-il revoir le code généré par IA différemment ?

Oui, avec encore plus d’attention. Les outils d’IA produisent du code qui paraît plausible mais qui peut faire référence à des fonctions inexistantes (hallucinations), copier des licences incompatibles, ou suivre des patterns obsolètes. Le relecteur doit traiter le code généré comme du code écrit par un junior très productif mais non fiable.

Comment gérer un désaccord persistant entre auteur et relecteur ?

Quand un échange dépasse trois allers-retours sur le même point, basculer en synchrone : appel de quinze minutes ou pair-programming sur la zone concernée. L’asynchrone amplifie les malentendus ; le synchrone résout en quelques minutes ce qui prendrait des jours par écrit.

Doit-on relire son propre code avant de demander une revue ?

Toujours. La première revue de la PR est celle de l’auteur sur son propre diff, juste avant de cliquer sur « Create pull request ». Cette pratique attrape une fraction notable des problèmes que les relecteurs auraient remontés.

Comment former un junior à la revue de code ?

Faire des revues à deux : un senior et le junior regardent la même PR ensemble pendant trente minutes. Le senior verbalise ce qu’il regarde, dans quel ordre, pourquoi. Cinq sessions comme ça forment plus efficacement que dix lectures de guide.

Est-il acceptable de mettre un cœur ou un emoji dans un commentaire de revue ?

Oui, et c’est même utile. Les emojis adoucissent le ton sans diluer le contenu. Un commentaire technique précis suivi de « 👍 belle approche sur la partie cache » apporte un signal positif que la version sèche n’a pas. À éviter : surcharger d’emojis, ce qui rend la revue infantile.