Un développeur soumet une pull request ajoutant un calcul de réduction à un service de paiement. Les tests sont concluants et le diff est court. Un relecteur l'approuve en deux minutes avec un simple « LGTM ». Trois mois plus tard, un collègue doit modifier cette même fonction et découvre qu'elle mélange règles de tarification, arrondi et accès à la base de données. Personne ne peut affirmer avec certitude ce qu'elle est autorisée à faire.
Il s'agit d'un exemple, et non d'un incident documenté. Il montre ce que doit produire la revue de code par les pairs lorsqu'elle sert d'activité d'apprentissage : un relecteur capable d'identifier une modification plausible, de repérer le problème qui n'est pas encore un bug et de l'expliquer de manière à ce que l'auteur puisse agir en conséquence.
Ce guide s'adresse aux responsables et aux gestionnaires de projets d'ingénierie. Il explique comment concevoir exercices de revue de code Ce guide vise à développer intentionnellement cette compétence, plutôt que de compter sur le hasard pour que les relecteurs l'acquièrent. Il aborde le problème de performance, les lacunes à identifier, la structuration de la préparation et de la pratique, un exemple concret et la manière de vérifier l'application de cette compétence lors de relectures réelles. Faites valider chaque cas, défaut et critère par des ingénieurs seniors avant toute utilisation.
Que sont les exercices de revue de code ?
Les exercices de revue de code sont des tâches pratiques structurées au cours desquelles un développeur examine une modification préparée, explique ses observations et leur importance, et reçoit un retour sur la qualité de cette explication. Ils diffèrent des revues effectuées quotidiennement par votre équipe. La modification est choisie à l'avance, les problèmes qu'elle soulève sont connus, et l'objectif est d'améliorer les compétences du relecteur plutôt que de déployer la modification.
Faits rapides
| Questionne toi | Réponse courte |
|---|---|
| Quelle est la tâche ? | Expliquez les conclusions de l'analyse et fournissez des commentaires sur lesquels l'auteur pourra agir. |
| Quel est votre score ? | Exactitude des résultats et utilité de l'explication. |
| Le comptage des défauts est-il suffisant ? | Non. Les évaluations ne se limitent pas aux défauts ; un exercice qui ne récompense que le nombre de bugs encourage donc de mauvaises habitudes. |
| Quelle est la demande cognitive ? | Analysez et évaluez un design, puis formulez une meilleure proposition. |
| Qui valide l'affaire ? | Un responsable d'ingénierie ou un ingénieur senior propriétaire du code source. |
| Que ne peuvent pas corriger les exercices ? | Délais d'examen, propriété incertaine et pression pour fusionner rapidement. |
| Comment savez-vous que cela a fonctionné ? | Un changement nouveau et imprévu est examiné au regard de critères convenus, suivi d'un suivi des évaluations réelles. |
1. Décrivez le problème de performance
Commencez par énoncer la tâche en une phrase : face à une modification, le relecteur explique ce qu’il a constaté, pourquoi c’est important et comment l’auteur pourrait y remédier. « Explique » est essentiel. Repérer un problème représente la moitié du travail. L’autre moitié consiste à le formuler de manière à ce qu’un collègue ayant un point de vue différent puisse le comprendre, l’évaluer et agir en conséquence.
Les recherches sur les revues de code modernes encouragent à aller au-delà de la simple chasse aux bogues. Dans une étude menée chez Microsoft, Bacchelli et Bird ont observé, interviewé et sondé des développeurs et des gestionnaires. Ils ont constaté que la détection des défauts restait la principale motivation des revues, mais que celles-ci portaient moins sur les défauts que ce que l'on imaginait. Elles offraient également d'autres avantages, tels que le partage des connaissances, la sensibilisation de l'équipe et la découverte de solutions alternatives. Les chercheurs ont décrit la compréhension du code et des modifications comme l'aspect clé des revues.Bacchelli et Bird, ICSE 2013Il s'agit d'une étude des équipes d'une seule entreprise ; utilisez-la donc comme une raison de concevoir en favorisant la compréhension, et non comme un critère pour la vôtre.
La norme d'examen publiée par Google va dans le même sens. Elle indique aux examinateurs qu'ils doivent privilégier l'approbation d'une modification dès lors qu'elle améliore nettement la santé globale du code, même si elle n'est pas parfaite, et elle précise que l'examen peut apprendre quelque chose de nouveau aux développeurs ; les commentaires qui aident à apprendre sont donc les bienvenus (Pratiques d'ingénierie de GoogleLes deux sources décrivent la révision comme un lieu où le jugement est exercé et transmis. C'est ce que vos exercices devraient préparer.
2. Diagnostiquer les lacunes en matière d'apprentissage et de contexte
Comparez cette tâche avec ce que votre programme actuel pratique et évalue.
- La pratique actuelle utilise-t-elle la tâche réelle ? Si les nouveaux relecteurs apprennent en lisant un guide de style puis en relisant des demandes de fusion réelles, ils s'exercent sur du code concret sans pouvoir se permettre de se tromper. Si l'évaluation consiste en un quiz sur l'étiquette de relecture, elle mesure la mémorisation des règles, et non la capacité à les appliquer à une modification.
- Quelle est la demande cognitive ? Dans la taxonomie de Bloom révisée, juger de la pertinence d'une conception et peser ses compromis relèvent des niveaux d'analyse et d'évaluation, tandis que proposer une meilleure structure correspond au niveau de création. Si vos exercices se limitent à la question « Que fait ce code ? », ils s'arrêtent à la compréhension. Notre guide… Faire correspondre les activités d'apprentissage à la taxonomie de Bloom montre comment adapter l'activité au niveau.
- Y a-t-il autre chose que le talent qui vous bloque ? Vérifiez le temps de relecture, les outils, la répartition des responsabilités et les normes de l'équipe. Si les relecteurs disposent de cinq minutes par demande de fusion, aucune explication détaillée ne sera fournie. Si les auteurs perçoivent chaque commentaire comme une critique, les relecteurs atténueront leurs conclusions jusqu'à ne plus rien dire. Signalez ces problèmes aux personnes compétentes.
3. Préparation, mise en pratique et retour d'information sur la conception
Attribuez une tâche distincte à chaque étape.
Préparation. Avant de commencer, vérifiez les besoins des relecteurs : la liste de contrôle de l’équipe, les principes de conception sur lesquels elle repose et la procédure pour interpréter les différences dans vos outils. Veillez à ce que cette étape soit rapide et à leur propre rythme. Une vérification des connaissances ne fait que confirmer les prérequis et ne constitue pas une preuve de la capacité d’une personne à effectuer une relecture.
Pratique. Utilisez des modifications préparées avec un petit nombre de problèmes prédéfinis de différents types : un bug de correction, un problème de maintenabilité comme le mélange de responsabilités dans l’exemple d’ouverture, un nom peu clair ou un test manquant, et du code correct. Demandez au relecteur d’écrire le commentaire qu’il laisserait, de classer les problèmes par ordre de priorité et d’indiquer les informations supplémentaires dont il aurait besoin. Le tutoriel pratique de CodeRefinery illustre le processus : les participants ouvrent une demande de fusion contenant une petite faute de frappe et une erreur plus importante, puis la relectent en tant que pairs (CodeRefinery, Pratique de la revue de code). Créez le vôtre à partir de votre propre base de code afin que les conventions et les compromis soient réels.
Feedback. Faites le lien avec les décisions prises par le réviseur. « Vous avez remarqué le problème d'arrondi, mais votre commentaire disait simplement "cela semble incorrect" sans préciser quelle donnée le provoque » est plus utile que « 2 sur 4 trouvés ».
Saisie en direct ou révision asynchrone ? L'intervention en direct est particulièrement précieuse lorsqu'un problème est ambigu et que les relecteurs apprennent en entendant un ingénieur senior expliquer pourquoi il le soulèverait ou non. La relecture asynchrone suffit pour comparer les commentaires avec une relecture annotée par un expert.
4. Travaillez sur un exemple réaliste
À titre d'exemple, un responsable technique doit valider le cas et les critères de réponse avant toute utilisation.
L'affaire. Une modification ajoute un calcul de réduction à un service de paiement. Ses tests sont concluants. Une fonction applique les réductions en pourcentage et les réductions fixes, arrondit le résultat, enregistre la valeur dans la base de données et déclenche un événement. Elle comporte un test, pour une réduction en pourcentage unique.
La tâche. Le réviseur rédige les commentaires qu'il laisserait, hiérarchise ses préoccupations et indique ce qu'il aurait besoin de savoir avant d'approuver.
Une première tentative. « Tout semble correct, le test est réussi. Peut-être faudrait-il le scinder ? » Le relecteur a remarqué quelque chose, mais sans préciser quoi, pourquoi c’est important ni quelle solution adopter. L’auteur ne peut donc pas agir.
Commentaires et nouvelle tentative. L'animateur demande : quel problème une modification future de cette fonction risquerait-elle de causer ? Que demanderiez-vous à l'auteur d'ajouter avant de donner son accord ? La procédure de révision demande un commentaire précis sur chaque point soulevé, avec la justification et une suggestion.
Une tentative plus convaincante. La fonction applique deux types de réduction, arrondit, enregistre et publie un événement. Par conséquent, toute modification de l'arrondi pourrait affecter simultanément les données enregistrées et publiées. Je suggère de déplacer les règles de tarification dans une fonction dédiée, testable indépendamment. Le test actuel ne couvre qu'une réduction en pourcentage. Je demanderais une réduction fixe et une condition pour que le total soit nul. Je ne sais pas si l'événement est censé se déclencher lorsque le total est nul ; je suggère donc de poser la question à l'auteur. Ce commentaire énonce clairement le problème, en donne la raison, formule une suggestion concrète et indique ce que le relecteur ignore.
5. Évaluer les capacités et planifier le transfert
La preuve de compétence réside dans la performance face à un changement inédit que l'évaluateur n'a pas encore constaté. Évaluez la précision des conclusions et la pertinence des explications. Une grille d'évaluation simple utilise une échelle de 0 à 2 par critère :
| Critère | Preuves observables |
|---|---|
| Exécution des tâches | Identifie les points pertinents du changement et consigne les preuves pour chacun d'eux. |
| Raisonnement | Explique pourquoi chaque point d'intérêt est important, propose une alternative et indique ce qui reste incertain. |
| Frontières | Respecte les règles de révision de l'équipe et demande de l'aide ou des informations lorsque l'autorité ou le contexte font défaut. |
Ancrages : 0 signifie absent ou non justifié, 1 signifie partiel avec des omissions pertinentes et 2 signifie complet et justifié selon les critères convenus. Définissez les erreurs critiques séparément, par exemple l’approbation d’une modification présentant un risque de perte de données, afin qu’une bonne note globale ne puisse pas en masquer une. Adaptez les critères avec le responsable technique ; cette grille d’évaluation est une proposition initiale, et non une norme de préparation validée. Pour plus d’informations sur le raisonnement derrière la notation, consultez notre guide. Concevoir une pratique interactive avec des retours utiles.
Prévoyez le transfert. Après l'exercice, vérifiez un échantillon des véritables évaluations du réviseur quelques semaines plus tard, en utilisant les mêmes critères. Comparez-le avec une évaluation de référence réalisée avant la formation et définissez la population cible et le calendrier en amont. Tenez compte des autres changements survenus pendant la même période, tels qu'un nouvel outil d'évaluation ou un changement de personnel, avant de valider les exercices.
6. Réalisez l'exercice en direct ou à votre propre rythme avec AhaSlides
Vous pouvez organiser cet exercice en atelier ou laisser les réviseurs le réaliser individuellement. Lors d'une session en direct, présentez la modification préparée et utilisez des diapositives interactives pour la discussion.
- Choisir une réponse Pour répondre à la question « Quelle préoccupation soulèveriez-vous en premier ? », en utilisant les préoccupations proposées comme options. Présentez le classement avant de révéler le vôtre.
- Ouvert L'exercice consiste à « rédiger le commentaire que vous laisseriez ». Les relecteurs peuvent ainsi comparer leur formulation avec celle des autres, ce qui met en évidence leur capacité à formuler des explications claires.
- Échelle de notation pour répondre à la question « à quel point est-ce grave ? », afin que le groupe puisse identifier les divergences d’opinions et en discuter.
Pour les évaluateurs ne pouvant pas participer, la même séquence peut être utilisée à leur propre rythme, l'évaluation d'expert annotée étant affichée après chaque réponse. Toute affirmation concernant l'exécution du code, les intégrations ou les fonctionnalités d'IA doit être considérée comme non confirmée tant que vous ne l'avez pas testée avec vos propres données.
Si vous formez également des relecteurs sur le code généré par l'IA, consultez notre guide complémentaire sur Formation à la revue de code générée par l'IACe billet portait sur l'audit des résultats produits. Celui-ci explique comment les gens évaluent le travail des autres et comment ils expliquent leurs conclusions.
Des contraintes qui pourraient subsister
- L'heure de la révision. Un commentaire réfléchi prend plus de temps qu'un simple « LGTM », et les délais serrés incitent à privilégier la version courte.
- Normes d'équipe. Si les commentaires sont perçus comme une critique personnelle, les évaluateurs atténueront ou abandonneront leurs conclusions.
- Couverture du dossier. Un exercice permet de mettre en lumière plusieurs types de préoccupations. Une note ne reflète pas de manière générale le jugement d'un évaluateur.
- Transfert. Les performances lors d'un atelier ne sont pas les mêmes que celles dans une file d'attente très fréquentée, alors consultez également les avis réels.
Signalez ces problèmes aux commanditaires dès le début et prévoyez des corrections distinctes. Les exercices permettent d'améliorer la capacité d'un examinateur à observer et à expliquer. Ils ne créent ni le temps ni les normes.
Foire aux questions
Que sont les exercices de revue de code ?
Il s'agit d'exercices pratiques où un développeur examine une modification présentant des problèmes connus, rédige les commentaires qu'il formulerait et reçoit un retour sur leur exactitude et leur utilité. L'objectif est de développer les compétences du relecteur, et non de déployer la modification.
Comment évalue-t-on si le jugement d'un évaluateur s'est amélioré ?
Proposez-leur une modification inédite et évaluez les résultats et les explications selon des critères convenus. Quelques semaines plus tard, vérifiez un échantillon de véritables avis. Un questionnaire sur les règles d'évaluation confirme uniquement les prérequis.
La revue de code par les pairs consiste-t-elle principalement à trouver des bogues ?
La détection des anomalies reste une motivation essentielle, mais une étude menée chez Microsoft a révélé que les revues de code portaient moins sur les anomalies que prévu et favorisaient également le partage des connaissances et la cohésion d'équipe. Il est donc important de concevoir des exercices qui valorisent les explications et la compréhension, en plus du simple comptage des anomalies.
Par où commencer
Choisissez un type de changement fréquemment examiné par votre équipe. Rédigez l'énoncé des performances, demandez à un ingénieur senior de préparer un changement comportant trois ou quatre points critiques, et élaborez une grille d'évaluation à trois critères avec une échelle de 0 à 2 et une liste d'erreurs critiques. Testez-la auprès d'un petit groupe, puis comparez leurs prochains examens réels avec cette grille de référence.
Pour découvrir comment un exercice de révision peut être mené en direct avec votre propre équipe et réutilisé à votre propre rythme par la suite, explorez AhaSlides.
