Les revues de code sont une partie importante du cycle de vie des logiciels modernes. Malheureusement, de nombreux cycles sont gaspillés et le moral est entaché car il existe peu de directives données aux examinateurs (et aux personnes examinées) sur les commentaires constructifs et la communication écrite efficace. Vous trouverez ci-dessous quelques conseils pour un meilleur processus de révision de code.

Déterminez pourquoi vous faites des revues de code

Est-ce pour trouver des bugs ? Est-ce pour diffuser la connaissance de la base de code ? Est-ce pour trouver des problèmes d'architecture ? Qu'est-ce que les revues de code offrent à votre équipe ? Si vous ne connaissez pas la réponse à cette question, vous ne savez pas si elles fonctionnent bien.

Il est probablement préférable d'avoir cette conversation explicite avec votre équipe. Il est normal que les équipes les utilisent pour différentes choses, mais il est très important que l'auteur et le réviseur sachent quel est le résultat attendu d'une évaluation.

Au sein de notre équipe, je m'attends à ce que je partage du code principalement pour diffuser des informations sur les changements apportés aux bases de code et pour vérifier que je ne fais rien d'incroyablement stupide. Parfois, j'aurai besoin de conseils d'experts (par exemple, pour le travail en front-end ou dans des services que je consulte rarement). En général, j'essaie d'obtenir ces conseils avant de taguer quelqu'un dans une PR. Lorsque cela se produit, je pense qu'il est préférable de reconnaître explicitement que vous vous attendez à ce que cette personne soit l'expert, afin qu'elle puisse examiner de plus près et peut-être vous aider lors d'un déploiement.

Automatisez votre guide de style

Si la réponse à la question « pourquoi faire des revues de code » inclut « s’assurer que le code suit un style cohérent », arrêtez-la. Il est difficile de réviser un code mal formaté. Et il est vraiment très difficile de vérifier à la fois l’exactitude et le style du code sans faire plusieurs passages. Il est également très démoralisant pour les nouveaux ingénieurs sur un projet de regarder leur PR et de voir des dizaines de commentaires de style. Il existe d’excellents outils de style automatisés qui peuvent automatiquement styliser votre code et vous devriez les utiliser. Dans mon équipe en particulier, nous nous efforçons d’utiliser Scalariform pour nos projets Scala et Rubocop pour nos projets Ruby. En aucun cas, en 2017, les ingénieurs ne devraient résoudre manuellement les problèmes de formatage.

En guise de solution de secours, dans les cas où l'automatisation n'a pas été mise en place, il est préférable que le réviseur corrige lui-même la mise en forme au lieu d'ajouter des commentaires à l'auteur (cela est doublement vrai lorsque vous révisez le code de votre propre coéquipier). Les petites choses peuvent être traitées directement dans l'interface utilisateur de GitHub et nous ne devrions pas hésiter à ajouter quelques commits inutiles qui seront de toute façon écrasés avant la fusion.

Proposez des suggestions, pas des ordres

Ne dites pas à un contributeur qu'il a fait quelque chose de mal dans une remarque de révision de code. Proposez une suggestion et demandez-lui ce qu'il en pense. Par exemple, jetez un œil aux commentaires ci-dessous :

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

Cela semble clairement très négatif. L'auteur peut se sentir sur la défensive et lancer une discussion inutile, même si cela n'apporte que peu d'avantages ; ou pire, l'auteur peut se sentir moins utile et suivre aveuglément la suggestion. Dans les deux cas, des commentaires comme celui-ci causent un véritable préjudice.

La meilleure chose que vous puissiez faire est de proposer une suggestion, non pas en tant que gardien, mais en tant que personne qui essaie d’en savoir plus sur les modifications apportées au code (même si vous êtes vraiment un gardien).

Que pensez-vous de prendre ceci avec ce qui précède et d'extraire une fonction ?

Pourquoi vos commentaires devraient-ils paraître si hésitants ? Parce que vous examinez le code de votre collègue. Vous devez l'inviter à expliquer poliment ce qui se passe ou à remarquer que vous avez fait une meilleure suggestion. Ne pas avoir de bonnes manières à cet égard élimine la possibilité de discussion pour une partie importante de la population.

Parlons de ma principale bête noire en matière de revues de code…

Pourquoi n'as-tu pas...

Demander à un « pourquoi tu ne l'as pas fait La question « ” implique un grand nombre de choses, dont aucune n’est constructive ou positive. Elle suppose que l’auteur du code a déjà pris en compte votre suggestion et en a explicitement choisi une autre, ce qui n’est peut-être pas le cas. Elle implique que votre alternative est évidemment supérieure (en particulier dans le cas particulier de « pourquoi n'as-tu pas simplement... '), et que vous exigez que l'auteur justifie sa solution par rapport à celle-ci. Cela implique que ce qui peut être considéré comme une simple suggestion est, en fait, la solution par défaut.

Chaque fois que je révise du code et que mon arrogance doit être vérifiée, j'essaie de proposer 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 ont un biais profondément négatif. Nous avons tendance à interpréter les communications neutres comme négatives et les communications positives comme neutres, ce qui est une source de grande consternation lors des revues de code. Pour lutter contre cela, efforcez-vous d'être ouvertement positif.

La concision peut être interprétée comme une impolitesse ou un manque de considération. Évitez en particulier d'ajouter un commentaire de deux ou trois mots.

Utilisez les revues de code comme un exercice d'apprentissage

Mon opinion sincère, non étayée par des données, est que la qualité et l'exactitude du code ne sont que marginalement améliorées par une révision du code par un gardien. Il est rare qu'un réviseur partage le même niveau de perspicacité que la personne qui a rédigé le code (enfin, sauf dans le cas mentionné ci-dessus, de la « révision par un expert »). Un meilleur modèle consiste à considérer les révisions de code comme un exercice d'apprentissage pour le réviseur, c'est-à-dire pour comprendre les modifications apportées au code et pour approfondir sa compréhension de la base de code. Je pense que ce nivellement donne à leurs questions et remarques le poids approprié et permet une discussion plus saine sur la base de code plus large et sur la façon dont les modifications interagissent avec elle.

Bien sûr, vous n’êtes pas obligé de faire tout cela pour être plus gentil dans vos critiques.

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

Pour recevoir une révision de code, vous devez suivre les mêmes suggestions dans l'ordre inverse. Reconnaissez que des commentaires concis ne signifient pas que le réviseur a une moins bonne opinion de vous. Reconnaissez que les « ordres » ne sont généralement que des suggestions mal formulées et une invitation à réfléchir au problème d'une manière (potentiellement différente). Reconnaissez que presque tout ce qui est écrit est plus négatif que prévu et laissez beaucoup de latitude à vos coéquipiers.

Il est facile d'imaginer que les révisions brutales du code sont un rituel qui conduit aux meilleurs résultats. D'après mon expérience, les ingénieurs sont beaucoup plus sensibles aux critiques qu'ils ne le laissent paraître, et ils sont beaucoup plus disposés à se faire prendre pour des coupables s'ils se sentent comme des collaborateurs plutôt que des accusés. Prenez quelques minutes supplémentaires pour ajouter un peu de gentillesse à vos révisions, et je pense que vous constaterez que vos révisions sont beaucoup plus productives et vous permettront de vous sentir mieux à la fin de la journée.

^{*Cet article a été initialement publié sur Blog personnel de Cory Chamblin Nous avons pensé que cela serait utile aux lecteurs de notre blog, nous avons donc décidé de le partager ici également.}