Les ~10 préceptes de la revue de code

Chez Marmelab, nous sommes convaincus des apports de la revue de code, que nous pratiquons quotidiennement. Mais faire une revue de code n'est pas inné, et savoir repérer et faire des retours constructifs demande un véritable apprentissage. Je vous propose, dans ce billet, une liste des points qui me semblent primordiaux pour bien mener sa revue (huhu... vous l'avez?).

Le contexte tu comprendras

La première chose à faire, avant même de commencer à lire le code, est de bien comprendre l'objet de ce code. S'agit-il d'un bug-fix, d'une feature, d'un refactoring? Et quelle est la feature? Que cherche à corriger ce code ?

Pour cela, le développeur à l'origine du code doit vous apporter suffisamment de contexte pour vous permettre de comprendre le plus rapidement possible de quoi il retourne. N'hésitez donc pas à faire un premier retour pour demander des précisions si l'objet de la modification n'est pas clair. Chez Marmelab, nous avons l'habitude d'accompagner nos PR d'un screenshot ou d'une capture vidéo pour les illustrer.

Comprendre les enjeux de la modification permet d'aborder le code en connaissance de cause.

Le projet tourner tu feras

L'idéal, lors d'une revue de code, est de faire un checkout, de faire tourner le code sur son poste, et de tester l'objet de la modification. Cela complète la prise de connaissance du contexte et permet par la même occasion de valider le développement.

Dans la pratique, ça n'est pas une étape systématique, mais lorsque le contexte n'est pas complètement clair, ou lorsqu'un doute subsiste sur la compréhension du code, cela aide à formaliser la modification.

Des suggestions tu feras

Github permet, via son interface de revue de code, de suggérer des modifications que le développeur pourra accepter, créant directement un commit. Lorsqu'il s'agit de petits changements, comme une typo, il est parfois plus efficace de donner directement le code modifié de cette manière que de faire un commentaire.

Bienveillant tu resteras

Que l'on fasse une remarque sur une coquille, ou sur la manière dont telle partie est codée, il ne s'agit pas de pointer du doigt, mais de se faire progresser mutuellement. Dans cette optique, rester le plus neutre possible est important, afin que la remarque ne vienne pas comme un jugement, mais comme une opportunité d'améliorer les choses.

Il arrive bien sûr quelques fois que le code que l'on lit nous hérisse le poil. Dans ces cas là, plutôt que de juste dire que le code est mauvais, il est plus intéressant d'expliquer en quoi il est mauvais. À l'inverse, si vous êtes l'auteur, laissez de côté votre susceptibilité.

De l'empathie tu auras

Il est toujours plus facile d'avoir un regard critique lorsque nous lisons un code qui n'est pas le nôtre. Aussi, il est important d'essayer de se mettre à la place de l'autre, et de comprendre ce qui l'a mené à cette solution. Au lieu de se dire "mais c'est quoi ce code ???", il faut plutôt se demander "qu'est-ce qui explique ce code ?". Cela nécessite d'échanger avec le développeur et nous mène à notre prochain point.

Des questions tu poseras

Une revue de code permet aussi de questionner les développements réalisés. Poser des questions force l'auteur à raisonner sur ce qu'il a produit. N'hésitez donc pas à commenter par une simple question, ou une remarque ouvrant à une explication.

Apprendre tu devras

Une revue, c'est aussi une occasion d'apprendre de l'autre. En lisant le code d'un autre, on apprend une autre façon de coder, des méthodes, ou des outils que l'on ne connaissait pas. Profitez de cette occasion pour progresser et vous ouvrir l'esprit sur d'autres approches.

Refuser tu pourras

Lorsque l'on fait ses premières revues de code, il arrive qu'on ne se sente pas tout à fait légitime, et que l'on hésite à refuser une PR. Et bien j'ai une bonne nouvelle : vous êtes légitime, et si vous pensez qu'une modification est nécessaire avant de valider le code, refusez la PR. Ne pas la refuser, en estimant pourtant qu'il y a des modifications à faire, c'est donner l'impression que ces modifications sont secondaires, et que le travail est fini. Cela peut avoir pour effet des remarques qui ne seront jamais prises en compte : une fois le code validé et mergé, il est rare que l'on revienne dessus.

Conclusion

Cette liste n'est pas exhaustive ni très objective (en plus du fait que j'ai menti, car il n'y a pas 10 points...), mais ce sont les points qui me semblent les plus importants pour bien aborder les revues de code.

Gardez en tête que le but d'une revue de code est multiple :

• Elle permet de voir du code écrit par quelqu'un d'autre, facilitant ainsi le partage de connaissance et de responsabilité.
• Elle permet également un certain contrôle, une coquille est vite arrivée et arrive à tout le monde.
• Et elle permet finalement de veiller à la bonne qualité du code, en partageant des pratiques de codage.

Respectez les personnes et le code que vous relisez, essayez de comprendre les enjeux, et tout se passera bien.

À vos revues !