Les revues de code constituent une étape essentielle du cycle de vie des logiciels modernes. Malheureusement, de nombreuses revues sont gaspillées et le moral des équipes est mis à rude épreuve faute de directives claires concernant les retours constructifs et la communication écrite efficace, tant pour les relecteurs que pour les personnes relues. Voici quelques conseils pour améliorer votre processus de revue de code.

Déterminez pourquoi vous effectuez des revues de code.

L'objectif est-il de détecter les bugs ? De diffuser la connaissance du code source ? De déceler les problèmes d'architecture ? Qu'apportent les revues de code à votre équipe ? Si vous ignorez la réponse à cette question, vous ne pouvez pas évaluer leur efficacité.

Il est probablement préférable d'avoir cette conversation ouverte avec votre équipe. Il est normal que les équipes les utilisent à des fins différentes, mais il est essentiel que l'auteur et le relecteur comprennent tous deux le résultat attendu d'une relecture.

Au sein de notre équipe, je partage généralement du code pour diffuser les informations relatives aux modifications apportées aux bases de code et pour vérifier que je ne fais rien d'irréparable. Il m'arrive d'avoir besoin de conseils d'experts (par exemple, pour le développement front-end ou pour des services que j'utilise rarement). En général, je cherche à obtenir leur avis avant de mentionner quelqu'un dans une pull request. Dans ce cas, il est préférable de préciser que l'on attend de cette personne qu'elle soit experte, afin qu'elle puisse examiner le code de plus près et éventuellement nous aider lors d'un déploiement.

Automatisez votre guide de style

Si votre réponse à la question « Pourquoi effectuez-vous des revues de code ? » inclut « Garantir un style de code cohérent », oubliez cette idée. Il est difficile de relire un code mal formaté. Et il est extrêmement difficile de vérifier à la fois la correction et le style du code sans plusieurs relectures. De plus, il est très démotivant pour les nouveaux développeurs de découvrir des dizaines de commentaires de style sur leur pull request. Il existe d'excellents outils de style automatisés qui peuvent styliser automatiquement votre code ; vous devriez les utiliser. Dans mon équipe, nous privilégions Scalariform pour nos projets Scala et Rubocop pour nos projets Ruby. En aucun cas en 2017, les ingénieurs ne devraient corriger manuellement les problèmes de formatage.

En dernier recours, si l'automatisation n'est pas configurée, il est préférable que le relecteur corrige lui-même la mise en forme plutôt que d'ajouter des commentaires à l'auteur (cela est d'autant plus vrai lorsqu'il s'agit du code d'un collègue). Les petits problèmes peuvent être gérés directement dans l'interface GitHub et il ne faut pas hésiter à ajouter quelques commits superflus qui seront de toute façon supprimés avant la fusion.

Proposez des suggestions, pas des ordres.

Lors d'une revue de code, ne faites pas de remarques directes à un contributeur sur ses erreurs. Proposez-lui plutôt une suggestion et demandez-lui son avis. Par exemple, consultez les commentaires ci-dessous :

Ne répétez pas cela ici, extrayez une fonction.

Cela est clairement perçu comme très négatif. L'auteur risque de se mettre sur la défensive et d'entamer une discussion stérile, même si cela n'apporte que peu d'avantages ; pire encore, il pourrait se sentir dévalorisé et suivre aveuglément la suggestion. Dans les deux cas, ce genre de commentaires est préjudiciable.

Le mieux que vous puissiez faire est de faire une suggestion, non pas en tant que gardien du temple, mais en tant que personne qui essaie de comprendre les modifications apportées au code (même si vous êtes en réalité un gardien du temple).

Que pensez-vous de combiner cela avec ce qui précède et d'en extraire une fonction ?

Pourquoi formuler vos commentaires sur un ton si hésitant ? Parce que vous relisez le code d'un collègue. Vous devez l'inviter poliment à expliquer la situation ou à reconnaître qu'une de vos suggestions est plus pertinente. Un manque de courtoisie à cet égard empêche toute discussion avec une grande partie des utilisateurs.

Parlons de ce qui m'agace le plus dans les revues de code…

Pourquoi n'avez-vous pas…

Demander à un « pourquoi ne l'as-tu pas fait ? La question sous-entend beaucoup de choses, dont aucune n'est constructive ou positive. Elle suppose que l'auteur du code a déjà examiné votre suggestion et en a explicitement choisi une autre, ce qui n'est pas forcément le cas. Elle sous-entend que votre alternative est manifestement supérieure (surtout dans le cas particulier de « Pourquoi n'as-tu pas simplement… « », et que vous exigez que l’auteur justifie sa solution par rapport à cela. Cela sous-entend que ce qui peut être considéré comme une simple suggestion est, en réalité, la norme.

Lorsque je relis du code et que mon orgueil doit être remis en question, j'essaie de faire une suggestion. Que pensez-vous de… ' ou ' Qu'en pensez-vous… « » sont de bons substituts pour cette phrase.

Utilisez un langage ouvertement positif

Il est important de reconnaître que les communications écrites sont souvent teintées d'un biais négatif. Nous avons tendance à interpréter les communications neutres comme négatives et les communications positives comme neutres, ce qui est source de nombreuses difficultés lors des revues de code. Pour y remédier, privilégiez une attitude résolument positive.

La concision peut être perçue comme de l'impolitesse ou du manque de considération. Évitez notamment les commentaires de deux ou trois mots seulement.

Utilisez les revues de code comme exercice d'apprentissage

Mon opinion, sincère et non étayée par des données, est que la qualité et la correction du code ne sont que marginalement améliorées par une revue de code effectuée par un responsable. Il est rare qu'un relecteur possède le même niveau de compréhension que l'auteur du code (sauf, bien sûr, dans le cas d'une « revue par un expert »). Un modèle plus pertinent consiste à considérer les revues de code comme un exercice d'apprentissage pour le relecteur, c'est-à-dire pour qu'il comprenne les modifications apportées au code et approfondisse sa connaissance de la base de code. Je pense que cette approche donne plus de poids à leurs questions et remarques, et permet une discussion plus constructive sur la base de code dans son ensemble et sur l'impact des modifications.

Bien sûr, vous n'êtes pas obligé de faire tout cela pour être plus aimable dans vos commentaires.

Lors de la réception d'une revue de code

Pour recevoir une revue de code, suivez les mêmes conseils, mais à l'envers. Sachez que des commentaires laconiques ne signifient pas que le relecteur vous sous-estime. Comprenez que les « ordres » sont généralement des suggestions mal formulées, une invitation à aborder le problème sous un angle potentiellement différent. Sachez que presque tout ce qui est écrit est perçu plus négativement que prévu, et faites preuve de souplesse envers vos collègues.

Il est facile d'imaginer que les revues de code impitoyables constituent un rituel garantissant les meilleurs résultats. Or, d'après mon expérience, les ingénieurs sont bien plus sensibles à la critique qu'ils ne le laissent paraître, et ils acceptent plus facilement de reconnaître leurs erreurs s'ils se sentent comme des collaborateurs plutôt que comme des accusés. Prenez quelques minutes supplémentaires pour aborder vos revues avec bienveillance ; vous constaterez, je pense, qu'elles sont bien plus productives et que vous vous sentirez mieux en fin de journée.

^{*Cet article a initialement été publié sur Le blog personnel de Cory Chamblin Nous avons pensé que cela pourrait être utile à nos lecteurs, c'est pourquoi nous avons décidé de le partager ici également.}