Les Dents de la MR

ou le guide de survie aux revues de code

Qui n’a jamais redouté une revue de code ? Pourtant, cette étape est incontournable pour la réussite d’un projet.

Les revues de code effectuées au cours de Merge Request (MR) sur GitLab ou de Pull Request (PR) sur GitHub : certains les redoutent par peur de recevoir des critiques sur leur travail et d'autres à cause de la quantité de code à relire sans en perdre le fil. Pourtant, bien menées, les revues de code garantissent la qualité du code, la sécurité de l’application et la collaboration au sein de l'équipe. En revanche, si nous tombons dans certains pièges, cela peut nuire à la cohésion, générer des retards et accumuler de la dette technique.

Dans cet article, nous verrons ensemble l'importance des revues de code, les pièges communs qui peuvent freiner votre équipe et les bonnes pratiques à adopter en tant que relecteur ou en tant qu'auteur pour ne pas se heurter à ces obstacles en utilisant les bons outils techniques et méthodologiques.

Pourquoi les revues de code sont importantes

Assurer la qualité et la sécurité

Le but premier d'une revue de code est d'assurer la qualité et la sécurité des nouvelles additions au code du projet. Cette relecture permet de repérer les bugs, les vulnérabilités, les erreurs de logique, les cas limites à surveiller et les cas particuliers métiers à bien respecter.

De plus, le fait qu'une autre personne lise notre travail apporte un regard neuf sur celui-ci. Nous pouvons souvent manquer des erreurs flagrantes à force de travailler avec des œillères et parce que beaucoup d’entre nous avons un biais qui nous fait croire que tout ce que nous produisons est génial.

Partager les connaissances

Il n'y a rien de plus problématique que des connaissances mal transmises au sein d'une équipe : un départ en congés ou un arrêt maladie et il n'y a plus personne pour répondre aux questions sur le paramétrage d'un module ou sur le fonctionnement d'une méthode mal documentée. Les membres d’une équipe ne travaillent pas nécessairement sur les mêmes fonctionnalités, ce qui limite donc la visibilité de chacun sur l’évolution du projet.

Les revues de code sont un moyen simple de partager la connaissance ou, a minima, sensibiliser au moins une autre personne de notre équipe à une thématique avec laquelle elle n’est pas familière. Pour l'auteur, c'est un moyen de recevoir des informations sur les bonnes pratiques de code mises en place au sein de l'équipe. Pour le relecteur, c'est un moyen de garder un œil sur les évolutions récentes du projet réalisées par les autres. C'est une forme de partage de connaissances réalisée de manière incrémentale qui sera plus facile à assimiler qu'un point formel organisé à la hâte avant un départ en vacances, où l’on risquerait de surcharger notre interlocuteur.

Entretenir une cohérence dans le projet

Outre l'interception de bugs et autres erreurs, un code lisible, documenté et compréhensible est un code que nous pouvons maintenir et faire évoluer. Un code opaque est compliqué à faire évoluer avec le temps parce que nous finissons par bâtir autour plutôt que bâtir avec. Il peut même être dangereux car il devient difficile d'en percevoir les failles et les limites. 

La relecture des évolutions par un tiers permet d'assurer que le code n'est pas mis en commun avant d'avoir été compris par un autre cerveau et d’être conforme aux standards de code, de nommage et de documentation communément acceptés par les membres de l'équipe.

Mentorer

Les retours adressés lors de revues de code sont une opportunité pour les développeurs juniors d'intégrer de bonnes pratiques dans leur code, de s'apercevoir d'erreurs en amont et de développer un regard critique sur leur propre travail. Tout ceci facilite l’intégration au sein de l’équipe et permet d'inculquer une culture de l'amélioration continue chez chacun mais en particulier chez les personnes qui apprennent encore les rouages du métier.

Faire cohabiter les équipes

Enfin, dans les environnements où le code est cogéré (par exemple : une équipe de dev, SRE et SecOps), les revues de code deviennent une obligation.

Imaginez vous la situation suivante : une nouvelle fonctionnalité sur votre projet nécessite l’utilisation d’une API externe. Une clé d’API est ajoutée dans un fichier de configuration mais malheur ! Un développeur de votre équipe commit par erreur cette clé en clair sans qu’une personne de l’équipe SecOps n’ait été conviée à la revue de code. La clé est exposée au grand public. Des acteurs malveillants peuvent ensuite usurper vos identifiants et vous infliger des dégâts financiers.

C’est pour des situations similaires à celle décrite ci-dessus que l’on voudrait s'assurer que les modifications sur les portions de code ayant plusieurs responsables ne soient pas mises en commun avant que toutes les parties prenantes ne soient consultées. En forçant ainsi la revue par les bonnes personnes, on limite les erreurs ou les changements non validés par les experts du domaine.

Un moyen concret de définir des responsables pour les différentes parties d’un projet est d’utiliser un fichier “CODEOWNERS”, situé à la racine d’un dépôt Git. Chaque partie du code est donc associée à un propriétaire ou une équipe désignée. Une manière simple d’éviter les ambiguïtés sur "qui doit se charger de cette revue ?" ou bien “qui doit absolument voir cette modification ?”. Les plateformes comme GitHub ou GitLab vont ensuite utiliser ce fichier pour notifier automatiquement les propriétaires désignés lorsqu’une nouvelle revue de code touche leur domaine. Cela garantit que les bonnes personnes sont impliquées dans la revue.

Exemple de fichier CODEOWNERS :

# CODEOWNERS
# Format : <chemin> <utilisateur/équipe>

# Équipe Frontend
/src/frontend/ @equipe-frontend

# Équipe Backend + SRE pour les APIs
/src/backend/api/v1/ @equipe-backend @equipe-sre

# SecOps pour tout ce qui touche à la sécurité
**/security/ @equipe-secops

# DevOps pour les configurations Docker/Kubernetes
**/Dockerfile @equipe-devops
**/*.yml @equipe-devops

Comment les revues de code deviennent un frein

Bien que les revues de code soient un outil méthodologique puissant, mal exécutées par les auteurs ou les relecteurs, elles peuvent coûter très cher.

L'arbre qui cache la forêt

Les relectures de code nécessitent de la minutie mais attention à ne pas passer des heures sur des détails sans prendre de recul. Vous avez fait 20 retours sur des nommages de variables ou de méthodes et sur l'indentation ? Très bien mais vous n'avez rien dit sur le non-respect de l'architecture du projet et des erreurs sur les règles métiers ! Ces détails sont importants mais il ne faut pas que ces derniers vous aveuglent sur les problèmes plus profonds et impactants. 

Une revue de code de qualité ne se résume pas au nombre de retours formulés mais à l'impact de ces derniers sur le projet. 

La "petite évolution" de 2000 lignes

Celle-ci est destinée à ceux qui mettent à relire des branches longues comme "Guerre & Paix" la veille d'une livraison : découpez vos branches ! Cela ralentit grandement le processus de validation des revues de code, ce n’est agréable pour personne et, même avec la meilleure volonté du monde, un relecteur va forcément laisser passer des erreurs qui peuvent parfois être fatales.

Lorsqu'il y a trop de code à relire lors d'une revue, c'est alors la forêt qui peut cacher un arbre.

Critiquer le collègue vs critiquer le code

Je pense que tout le monde a déjà connu un professeur qui semblait durcir ou adoucir sa notation en fonction du nom inscrit en haut de la copie. Lors des revues de code, il faut veiller à bien critiquer le code et pas son collègue. De la même manière que nous cherchons à entretenir un code de qualité, il est aussi important d'entretenir la qualité des relations au sein d'une équipe. Il faut faire preuve d'empathie, éviter d'employer un langage excessivement accusateur et négatif dans ses retours pour ne pas démoraliser ou créer des tensions au sein de son équipe.

La revue de code doit être la plus objective possible, limiter l’influence des biais et critiquer le code, pas son auteur. 

La validation à l'aveugle

En opposition aux relecteurs trop zélés, il y a les relecteurs fantômes. Ceux qui survolent les nouvelles additions dans le code sans les inspecter en profondeur, qui laissent passer des énormités sans les relever, ceux qui ne relèvent pas les manquements aux standards établis et aux bonnes pratiques de code.

Valider du nouveau code sans le relire minutieusement permet d’aller vite mais va à l'encontre des objectifs de maintien de la qualité et de la sécurité.

Le bouchon

On pourrait avoir tendance à déléguer exclusivement les tâches de relecture aux plus sages de l'équipe. Cela permet d'avoir le regard le plus expert et un avis plus uniforme sur le code. Cependant, en particulier dans une grande équipe, cette approche peut vite générer des retards dans la validation des branches et donc dans la vitesse de réalisation du projet. Aussi, à force de charger les mêmes personnes avec les revues de code, nous les éloignons de la réalisation concrète du projet, ce qui peut les épuiser et réduire leur efficacité.

Les revues de code devraient être la responsabilité de chacun. Faites tourner la responsabilité des relectures pour accélérer les validations, transmettre la connaissance du projet et répartir la charge de ce travail.

Le standard de qualité

Bien que les caractéristiques principales de ce qui fait un code de qualité soient communément acceptées et répandues, il est important que tout le monde se réunisse pour se mettre d’accord sur les standards de qualité, de lisibilité et les bonnes pratiques qui peuvent être sujet à débat. Sans cela, plusieurs risques nous guettent. Les mêmes débats peuvent revenir en boucle. Si le nombre de relecteurs est limité, certains pourraient imposer leur vision. Il pourrait y avoir des incohérences de style et de qualité en fonction du relecteur.

Une autre manière de pallier ces problèmes serait d’avoir plusieurs relecteurs pour chaque revue, si la taille de l’équipe le permet, pour éviter d’avoir ce souci de vision unique et assurer un consensus sur le standard à adopter.

Un exemple assez répandu où le consensus peut manquer est le GitFlow. Certains nomment les branches de features avec le nom de la feature, d’autres avec un identifiant de ticket, certains veulent seulement une branche main qui reflète la production et d’autres veulent des branches de release pour bien séparer les versions, et puis il y a ceux qui, dans une équipe de 8 développeurs, veulent push directement dans le main (vécu). Toutes ces bonnes pratiques ont des biais individuels mais sont aussi influencées par la culture de l’équipe et de l’entreprise. L’important est donc de trouver un ensemble de pratiques solides mais adaptées à votre besoin.

Quelques bonnes pratiques de revues de code

Le contexte d'équipe, d'entreprise, le domaine métier ou la taille du projet vont définir ce qui est une bonne ou une mauvaise pratique pour vous. Cependant, certaines pratiques sont plus universelles que d’autres et peuvent s'appliquer dans un grand nombre de contextes.

• Soyez constructif dans vos retours. Il vaut mieux tourner ses retours sous forme de suggestions plutôt que de commandes. Par exemple : "as-tu pris en compte... ?" ou "que dirais-tu si à la place... ?". Il faut chercher à ouvrir des discussions pour mieux construire ensemble. De cette manière, nous ne brusquons pas l'autre, nous comprenons mieux ses choix et les changements sont plus facilement acceptés.
• Découpez vos évolutions. Rendez vos branches plus faciles à relire en réduisant leur taille.
• Posez des questions. Il vaut toujours mieux poser des questions sur un point qui ne vous semble pas clair plutôt que de supposer comprendre. Cela rendra le reste de la relecture plus clair et vous évitera de valider une modification sans en avoir réellement saisi le fond.
• Faites plus de pair reviews. Les échanges de vive voix sont une très bonne façon de réaliser ses revues de code. Plutôt que de communiquer de manière asynchrone et succincte via des retours écrits, le pair reviewing vous permettra d’avoir des échanges plus rapides et complets et c’est un excellent moyen de mentorer les juniors. Ainsi vos questions sont répondues plus rapidement et vos retours plus faciles à assimiler.
• Mettez de l’ordre dans vos retours. Avant d'évoquer les problèmes mineurs ou esthétiques, remonter les problèmes critiques comme les bugs et les failles de sécurité.
• Vérifiez les tests en priorité. Une bonne revue de code passe souvent d'abord par la vérification des tests car ce sont eux qui témoignent de la conformité de l’évolution ou de la correction réalisée. Si vous êtes auteur, assurez de réaliser des tests complets et pertinents et si vous êtes relecteur, attardez vous sur les tests avant de valider le reste du code.
• Gardez un esprit ouvert. Les revues de code doivent être des opportunités d’apprentissage, jamais des séances de critique stérile.
• Justifiez vos retours. Si vous suggérez des modifications, expliquez l'impact qu'ils auront (performance, lisibilité, maintenabilité, sécurité, ...).
• Utilisez des checklists. Créez des listes de tâches à faire par les auteurs de revues de code avant de les soumettre et ainsi limiter le nombre de retours évitables comme par exemple sur la gestion des erreurs, la documentation ou la rédaction des tests unitaires.
• Mettez en place des outils. Certains outils permettent de corriger ou signaler automatiquement les défauts de qualité, de sécurité et de lisibilité.
  • Pour le formatage et le respect de standards de code vous pouvez utiliser un linter (par exemple : ESLint), un formateur de code (par exemple : Prettier) dans vos éditeurs de code, IDE ou vos scripts de pre-commits pour corriger, et voir les mauvaises pratiques et les problèmes de lisibilité avant même d’ouvrir vos demandes de relecture de code.
  • Vous pouvez intégrer des outils à vos pipelines pour vérifier que le code respecte bien les standards de l’entreprise ou pour analyser et détecter en avance les bugs, la dette technique et les vulnérabilités de vos branches (par exemple : SonarQube).
• Soyez spécifiques. Pour les relecteurs, les commentaires tels que "à corriger." ou "je n'aurais pas fait ça." ne sont pas constructifs et n'aident pas à comprendre le problème. Il est important d'être spécifique. Pour les auteurs, commentez et décrivez votre travail si vous savez que certaines parties peuvent porter à confusion.
• Prenez en compte le contexte. Il est important de dézoomer et prendre en compte ce qui entoure ces nouvelles additions. Parfois la réponse au retour que vous êtes en train de formuler se trouve quelques lignes plus haut.
• Ne sous-estimez pas les petits changements. Même si un petit nombre de lignes a été changées, elles peuvent malgré tout engendrer des bugs et de la dette technique.
• Ne bloquez pas une branche pour des problèmes mineurs. Si la validation d’une branche est bloquante pour l'avancée de l'équipe mais que les retours issus de sa relecture portent sur des problèmes mineurs, il peut être judicieux de donner ces corrections à faire dans une nouvelle tâche à part.

Les revues de code, un art à maîtriser pour des projets plus solides

Les revues de code ne sont pas une simple formalité, mais bel et bien un pilier essentiel de la qualité logicielle et de la cohésion d'une équipe. Elles peuvent être redoutées, perçues comme une source de stress ou une perte de temps, mais lorsqu'elles sont bien menées, avec les bons outils et les bonnes méthodologies, elles deviennent un levier puissant pour améliorer la qualité du code, limiter les vulnérabilités, partager les connaissances et renforcer la collaboration.

Cependant, attention aux pièges : une revue de code mal menée peut vite transformer cet outil en un frein à la productivité, réduire la motivation et fragiliser l'unité du groupe. Que ce soit en s'attardant sur des détails superficiels, en formulant des retours excessivement négatifs ou en chargeant toujours les mêmes personnes avec cette responsabilité, les risques sont nombreux. L'équilibre est la clé : entre sens du détail et prise de vue d’ensemble, entre exigence et bienveillance, entre automatisation et discussion humaine.

En adoptant les bonnes pratiques, comme découper les évolutions pour plus facilement les relire, justifier ses retours, utiliser les outils adaptés et garder un esprit ouvert, les revues de code deviennent un outil d'amélioration continue pour le projet et les individus. Elles ne sont plus une épreuve mais une opportunité de grandir, individuellement et collectivement.

Alors, la prochaine fois que vous soumettrez ou réaliserez une revue de code, rappelez-vous : vous ne critiquez pas un collègue, vous construisez un projet. Et c'est ensemble que vous le rendrez plus robuste, qualitatif et maintenable.

La revue de code évolue également avec l'ère de l’intelligence artificielle. En effet, des outils comme GitHub Copilot ou CodeRabbit ont fait leur entrée dans le milieu de la revue de code pour automatiser l’analyse de code et la suggestion d'améliorations. La revue de code par IA nous promet donc des gains d'efficacité ainsi que des retours plus détaillés et personnalisés. Malgré tout, nous ne sommes pas à l’abri des hallucinations et des incompréhensions contextuelles concernant la logique métier ou l’architecture logicielle.

Et vous, quelles sont vos astuces pour rendre les revues de code plus efficaces et agréables ?