Apporter à votre équipe un état d'esprit sain pour l'examen du code

Une « révision de code » est un moment du processus de développement au cours duquel vous (en tant que développeur) et vos collègues travaillez ensemble et recherchez les bogues dans un morceau de code récent avant qu'il ne soit publié. Dans un tel moment, vous pouvez être soit l'auteur du code, soit l'un des réviseurs.

Lors d'une revue de code, vous n'êtes peut-être pas sûr de ce que vous recherchez. D'un autre côté, lorsque vous soumettez une révision de code, vous ne savez peut-être pas quoi attendre. Ce manque d'empathie et de fausses attentes entre les deux parties peut déclencher des situations malheureuses et précipiter le processus jusqu'à ce qu'il se termine par une expérience désagréable pour les deux parties.

Dans cet article, je vais partager comment ce résultat peut être modifié en changeant votre état d'esprit lors d'une révision de code :

• Comme une équipe
• En tant qu'auteur
• En tant que critique

Travailler en équipe

Favoriser une culture de collaboration

Avant de commencer, il est fondamental de comprendre pourquoi le code doit être révisé. Le partage des connaissances et la cohésion d'équipe sont bénéfiques pour tout le monde, cependant, si cela est fait avec un mauvais état d'esprit, une révision de code peut prendre beaucoup de temps avec des résultats désagréables.

L'attitude et le comportement de l'équipe doivent adopter la valeur d'une collaboration sans jugement, dans le but commun d'apprendre et de partager , quelle que soit l'expérience de quelqu'un d'autre.

Inclure les revues de code dans vos estimations

Une révision complète du code prend du temps. Si une modification a pris une semaine pour être effectuée, ne vous attendez pas à ce que la révision du code prenne moins d'une journée. Ça ne marche pas comme ça. N'essayez pas de précipiter une révision du code ni de le considérer comme un goulot d'étranglement.

Les révisions de code sont aussi importantes que l'écriture du code proprement dit. En équipe, n'oubliez pas d' inclure des revues de code dans votre flux de travail et de définir des attentes quant à la durée d'une revue de code, afin que tout le monde soit synchronisé et confiant dans son travail.

Gagnez du temps grâce aux directives et à l'automatisation

Un moyen efficace de garantir des contributions cohérentes est d'intégrer un modèle de demande d'extraction dans le projet. Cela aidera l'auteur à soumettre un PR sain avec une description complète. Une description de PR doit expliquer quel est l'objectif du changement, la raison sous-jacente et comment le reproduire. Les captures d'écran et les liens de référence (problème Git, fichier de conception, etc.) sont la touche finale d'une soumission explicite.

Faire tout cela empêchera les premiers commentaires des examinateurs demandant plus de détails. Une autre façon de rendre les révisions de code moins pointilleuses consiste à utiliser des linters pour trouver des problèmes de formatage et de qualité de code avant même qu'un réviseur ne s'implique. Chaque fois que vous voyez un commentaire répétitif pendant le processus de révision, cherchez des moyens de le minimiser (avec de meilleures directives ou une automatisation du code).

Rester étudiant

N'importe qui peut faire une révision de code, et tout le monde doit recevoir une révision de code, quel que soit son niveau d'ancienneté. Recevez toute rétroaction avec gratitude comme une occasion d'apprendre et de partager des connaissances. Considérez tout commentaire comme une discussion ouverte plutôt que comme une réaction défensive. Comme le dit Ryan Holiday :

« Un amateur est sur la défensive. Le professionnel trouve qu'apprendre (et même, occasionnellement, se montrer) est agréable ; ils aiment être mis au défi et humbles, et s'engagent dans l'éducation comme un processus continu et sans fin. (...)"

— Ryan Holiday, L'ego est l'ennemi

Restez humble car à la seconde où vous cessez d'être étudiant, vos connaissances deviennent fragiles.

L'art de sélectionner les examinateurs

À mon avis, choisir les réviseurs est l'une des décisions les plus importantes pour une révision de code efficace et saine en équipe.

Supposons que votre collègue soumette une révision de code et décide de taguer "tout le monde" car, inconsciemment, il/elle pourrait vouloir accélérer le processus, fournir le meilleur code possible ou s'assurer que tout le monde est au courant du changement de code. Chacun des examinateurs reçoit une notification, puis ouvre le lien PR et voit beaucoup de personnes marquées comme examinateurs. La pensée de "quelqu'un d'autre le fera" apparaît dans leur esprit, ce qui conduit à ignorer la révision du code et à fermer le lien.

Puisque personne n'a encore commencé l'examen, votre collègue rappellera à chacun des examinateurs de le faire, c'est-à-dire en créant une pression sur eux. Une fois que les examinateurs commencent à le faire, le processus d'examen prend une éternité car chacun a sa propre opinion et c'est un cauchemar de parvenir à un accord commun. Pendant ce temps, celui qui a décidé de ne pas revoir le code, est ensuite spammé avec des zillions de notifications par e-mail avec tous les commentaires de révision, créant ainsi du bruit dans leur productivité.

C'est quelque chose que je vois se produire plus que je ne le souhaiterais : des demandes d'extraction avec un groupe de personnes identifiées comme réviseurs et se terminant, ironiquement, par une révision de code non productive.

Il existe des flux efficaces communs lors de la sélection des réviseurs : Un flux possible consiste à choisir deux ou trois collègues qui connaissent le code et à leur demander d'être des réviseurs. Une autre approche, expliquée par l'équipe Gitlab, consiste à avoir un flux de révision enchaîné dans lequel l'auteur choisit un relecteur qui en choisit un autre jusqu'à ce qu'au moins deux relecteurs soient d'accord avec le code. Quel que soit le flux que vous choisissez, évitez d'avoir trop de réviseurs . Pouvoir faire confiance au jugement de vos collègues en matière de code est la clé pour mener une revue de code efficace et saine.

Avoir de l'empathie

Repérer les morceaux de code à améliorer n'est qu'une partie d'une révision de code réussie. Il est tout aussi important de communiquer ces commentaires de manière saine en faisant preuve d'empathie envers vos collègues.

Avant d'écrire un commentaire, n'oubliez pas de vous mettre à la place des autres. Il est facile d'être mal compris lors de l'écriture, alors révisez vos propres mots avant de les envoyer. Même si une conversation commence à être moche, ne la laissez pas vous affecter – restez toujours respectueux. Bien parler aux autres n'est jamais une mauvaise décision.

Savoir faire des compromis

Lorsqu'une discussion n'est pas résolue rapidement, amenez-la à un appel ou à un chat personnel. Analysez ensemble s'il s'agit d'un sujet qui mérite de paralyser la demande de changement en cours ou s'il peut être abordé dans une autre.

Être flexible mais pragmatique et savoir équilibrer efficacité (livraison) et efficacité (qualité). C'est un compromis à faire en équipe. Dans ces moments-là, j'aime penser à une révision de code comme une itération plutôt qu'une solution finale. Il y a toujours place à l'amélioration au prochain tour.

Examens de code en personne

Rassembler l'auteur et l'examinateur dans un style de programmation en binôme peut être très efficace. Personnellement, je préfère cette approche lorsque la révision du code implique des changements complexes ou qu'il y a une opportunité pour un grand partage de connaissances. Bien qu'il s'agisse d'une révision de code hors ligne, c'est une bonne habitude de laisser des commentaires en ligne sur les discussions, en particulier lorsque des modifications doivent être apportées après la réunion. Ceci est également utile pour tenir les autres réviseurs en ligne informés.

Apprendre des résultats de la révision du code

Lorsqu'une revue de code a subi beaucoup de changements, a pris trop de temps ou a déjà eu trop de discussions, rassemblez votre équipe et analysez les causes et les actions qui peuvent en être prises. Lorsque la revue de code est complexe, diviser une tâche future en tâches plus petites facilite chaque revue de code.

Lorsque l'écart d'expérience est important, l'adoption de la programmation en binôme est une stratégie aux résultats incroyables, non seulement pour le partage des connaissances, mais également pour la collaboration et la communication hors ligne. Quel que soit le résultat, visez toujours une équipe saine et dynamique avec des attentes claires.

En tant qu'auteur

L'une des principales préoccupations lorsque l'on travaille sur une révision de code en tant qu'auteur est de minimiser la surprise du réviseur lors de la première lecture du code. C'est la première étape vers une révision de code prévisible et fluide. Voici comment vous pouvez le faire.

Établir une communication précoce

Ce n'est jamais une mauvaise idée de parler avec vos futurs réviseurs avant de trop coder. Chaque fois qu'il s'agit d'une contribution interne ou externe, vous pouvez faire un raffinement ensemble ou un peu de programmation en binôme au début du développement pour discuter des solutions.

Il n'y a rien de mal à demander de l'aide dans un premier temps. En fait, travailler ensemble en dehors de l'examen est une première étape importante pour éviter les erreurs précoces et garantir un premier accord. Dans le même temps, vos relecteurs prennent connaissance d'une future revue de code à faire.

Suivez les directives

Lorsque vous soumettez une demande d'extraction à examiner, n'oubliez pas d'ajouter une description et de suivre les directives. Cela évitera aux examinateurs de passer du temps à comprendre le contexte du nouveau code. Même si vos examinateurs savent déjà de quoi il s'agit, vous pouvez également profiter de cette occasion pour améliorer vos compétences en rédaction et en communication.

Soyez votre premier évaluateur

Voir votre propre code dans un contexte différent vous permet de trouver des choses qui vous manqueraient dans votre éditeur de code. Faites une revue de code de votre propre code avant de demander à vos collègues. Ayez un état d'esprit de réviseur et parcourez vraiment chaque ligne de code.

Personnellement, j'aime annoter mes propres revues de code pour mieux guider mes relecteurs. Le but ici est d'éviter les commentaires liés à un éventuel manque d'attention et de s'assurer que vous avez suivi les consignes de contribution. Essayez de soumettre une révision de code comme vous aimeriez en recevoir une.

Sois patient

Après avoir soumis une révision de code, ne sautez pas directement dans un nouveau message privé demandant à vos réviseurs de "jeter un coup d'œil, cela ne prend que quelques minutes" et d'avoir indirectement envie de cet emoji pouce levé. Essayer de presser vos collègues de faire leur travail n'est pas un état d'esprit sain. Au lieu de cela, faites confiance au flux de travail de vos collègues car ils vous font confiance pour soumettre une bonne révision de code. En attendant, attendez qu'ils vous rappellent lorsqu'ils seront disponibles. Ne considérez pas vos critiques comme un goulot d'étranglement. N'oubliez pas d'être patient car les choses difficiles prennent du temps.

Soyez un auditeur

Une fois qu'une révision de code est soumise, des commentaires viendront, des questions seront posées et des modifications seront proposées. La règle d'or ici est de ne pas considérer les commentaires comme une attaque personnelle. N'oubliez pas que tout code peut bénéficier d'un point de vue extérieur .

Ne considérez pas vos critiques comme un ennemi. Au lieu de cela, profitez de ce moment pour mettre de côté votre ego, acceptez que vous fassiez des erreurs et soyez ouvert à apprendre de vos collègues, afin que vous puissiez faire un meilleur travail la prochaine fois.

En tant que critique

Planifiez à l'avance

Lorsqu'on vous demande d'être un réviseur, n'interrompez pas les choses tout de suite. C'est une erreur courante que je vois tout le temps. La révision du code demande toute votre attention, et chaque fois que vous changez de contexte de code, vous diminuez votre productivité en perdant du temps à recalibrer votre concentration. Au lieu de cela, planifiez à l'avance en allouant des créneaux horaires de votre journée pour effectuer des révisions de code.

Personnellement, je préfère faire des révisions de code le matin ou après le déjeuner avant de choisir une autre de mes tâches. C'est ce qui fonctionne le mieux pour moi car mon cerveau est encore frais sans contexte de code précédent pour se déconnecter. De plus, une fois que j'ai terminé la révision, je peux me concentrer sur mes propres tâches, tandis que l'auteur peut réévaluer le code en fonction des commentaires.

Soyez solidaire

Lorsqu'une demande d'extraction ne respecte pas les directives de contribution, apportez votre soutien, en particulier aux nouveaux arrivants. Profitez de ce moment pour guider l'auteur afin d'améliorer sa contribution. En attendant, essayez de comprendre pourquoi l'auteur n'a pas suivi les directives en premier lieu. Peut-être y a-t-il place à l'amélioration dont vous n'aviez pas conscience auparavant.

Découvrez la branche et exécutez-la

Lors de la révision du code, faites-le fonctionner sur votre propre ordinateur, en particulier lorsqu'il implique des interfaces utilisateur. Cette habitude vous aidera à mieux comprendre le nouveau code et à repérer les choses que vous pourriez manquer si vous venez d'utiliser un outil de comparaison par défaut dans le navigateur qui limite votre portée de révision au code modifié (sans avoir le contexte complet comme dans votre éditeur de code) .

Demander avant d'assumer

Lorsque vous ne comprenez pas quelque chose, n'ayez pas peur de le dire et de poser des questions. Lorsque vous demandez, n'oubliez pas de lire d'abord le code environnant et évitez de faire des suppositions.

La plupart des questions rentrent dans ces deux types de catégories :

1. Question "comment"
   Lorsque vous ne comprenez pas comment quelque chose fonctionne ou ce qu'il fait, évaluez avec l'auteur si le code est suffisamment clair. Ne confondez pas le code simple avec l'ignorance. Il y a une différence entre un code difficile à lire et un code dont vous n'êtes pas conscient. Soyez ouvert pour apprendre et utiliser une nouvelle fonctionnalité linguistique, même si vous ne la connaissez pas encore profondément. Cependant, utilisez-le uniquement s'il simplifie la base de code.
2. Question "Pourquoi"
   Lorsque vous ne comprenez pas le "pourquoi", n'ayez pas peur de suggérer de commenter le code, surtout s'il s'agit d'un cas limite ou d'une correction de bogue. Le code doit être explicite lorsqu'il s'agit d'expliquer ce qu'il fait. Les commentaires sont un complément pour expliquer le pourquoi d'une certaine approche. Expliquer le contexte est très précieux lorsqu'il s'agit de maintenabilité et cela évitera à quelqu'un de supprimer un bloc de code qu'il pensait inutile. (Personnellement, j'aime commenter le code jusqu'à ce que je me sente sûr de l'oublier plus tard.)

Critique constructive

Une fois que vous avez trouvé un morceau de code qui, selon vous, devrait être amélioré, rappelez-vous toujours de reconnaître l'effort de l'auteur pour contribuer au projet et de vous exprimer de manière réceptive et transparente.

• Discussions ouvertes.
  Évitez de formaliser vos commentaires sous la forme d'un ordre ou d'une accusation du type « Vous devriez… » ou « Vous avez oublié… ». Exprimez vos commentaires sous forme de discussion ouverte au lieu d'une demande obligatoire. N'oubliez pas de commenter le code, pas l'auteur. Si le commentaire ne concerne pas le code, il ne devrait pas faire partie d'une révision de code. Comme dit précédemment, soyez solidaire. Utiliser une voix passive, parler au pluriel, exprimer des questions ou des suggestions sont de bonnes approches pour souligner l'empathie avec l'auteur.
  

Au lieu de « Extraire cette méthode d'ici… » préférez « Cette méthode devrait être extraite… » ou « Que pensez-vous de l'extraction de cette méthode… »

• Être clair.
  Un feedback peut facilement être mal interprété, surtout lorsqu'il s'agit d'exprimer une opinion plutôt que de partager un fait ou une ligne directrice. Rappelez-vous toujours de l'effacer tout de suite dans votre commentaire.

Pas clair : "Ce code devrait être…."

Opinion : "Je pense que ce code devrait être…"

Réalité : « Suivant [nos directives], ce code devrait être… ».

• Expliquer pourquoi.
  Ce qui est évident pour vous, ne l'est peut-être pas pour d'autres. Il ne s'agit jamais trop d'expliquer la motivation derrière vos commentaires, afin que l'auteur comprenne non seulement comment changer quelque chose, mais aussi quel en est l'avantage.

Opinion : "Je crois que ce code pourrait être..."

Expliqué : "Je pense que ce code pourrait être (…) car cela améliorera la lisibilité et simplifiera les tests unitaires."

• Donnez des exemples.
  Lorsque vous partagez une fonctionnalité de code ou un modèle avec lequel l'auteur n'est pas familier, complétez votre suggestion avec une référence à titre indicatif. Lorsque cela est possible, allez au-delà des documents MDN et partagez un extrait ou un exemple de travail adapté au scénario de code actuel. Lorsque la rédaction d'un exemple est trop complexe, soyez solidaire et proposez votre aide en personne ou par appel vidéo.

En plus de dire quelque chose comme "L'utilisation du filtre nous aidera à [motivation]", dites également : "Dans ce cas, cela pourrait être quelque chose comme : [extrait de code]. Vous pouvez vérifier [un exemple sur Finder.js]. En cas de doute, n'hésitez pas à me cingler sur Slack.

• Être raisonnable.
  Si la même erreur est commise plusieurs fois, préférez ne laisser qu'un seul commentaire à ce sujet et rappelez-vous que l'auteur doit également l'examiner à d'autres endroits. L'ajout de commentaires redondants ne fait que créer du bruit et peut être contre-productif.

Gardez le focus

Évitez de proposer des changements de code sans rapport avec le code actuel. Avant de suggérer un changement, demandez-vous s'il est strictement nécessaire à ce moment-là. Ce type de rétroaction est particulièrement courant dans les refactors. C'est l'un des nombreux compromis entre l'efficience et l'efficacité que nous devons faire en équipe.

En ce qui concerne les refactors, personnellement, j'ai tendance à préférer des améliorations petites mais efficaces . Ceux-ci sont plus faciles à examiner et il y a moins de risques d'avoir des conflits de code lors de la mise à jour de la branche avec la branche cible.

Définir les attentes

Si vous laissez une révision de code à moitié terminée, informez-en l'auteur, afin que les attentes en matière de temps soient sous contrôle. À la fin, faites également savoir à l'auteur si vous êtes d'accord avec le nouveau code ou si vous souhaitez le revoir plus tard.

Avant d'approuver une révision de code, demandez-vous si vous êtes à l'aise avec la possibilité de toucher à ce code à l'avenir. Si oui, c'est un signe que vous avez fait une révision de code réussie !

Apprenez à refuser une révision de code

Bien que personne ne l'admette, il faut parfois refuser une revue de code. Au moment où vous décidez d'accepter une révision de code mais que vous essayez de la précipiter, la qualité du projet est compromise ainsi que l'état d'esprit de votre équipe.

Lorsque vous acceptez de revoir le code de quelqu'un d'autre, cette personne fait confiance à vos capacités — c'est un engagement. Si vous n'avez pas le temps d'être un réviseur, dites simplement non à vos collègues. Je le pense vraiment; ne laissez pas vos collègues attendre une revue de code qui ne se fera jamais. N'oubliez pas de communiquer et de garder les attentes claires . Soyez honnête avec votre équipe et, mieux encore, avec vous-même. Quel que soit votre choix, faites-le sainement et faites-le bien.

Conclusion

Avec suffisamment de temps et d'expérience, faire des revues de code vous apprendra bien plus que de simples connaissances techniques. Vous apprendrez à donner et à recevoir des commentaires des autres, ainsi qu'à prendre des décisions en y réfléchissant davantage.

Chaque revue de code est une opportunité de grandir en tant que communauté et individuellement. Même en dehors des révisions de code, n'oubliez pas de favoriser un état d'esprit sain jusqu'au jour où cela viendra naturellement à vous et à vos collègues. Parce que c'est le partage qui nous rend meilleurs !

Lectures complémentaires sur SmashingMag :

• Travailler ensemble : comment les concepteurs et les développeurs peuvent communiquer pour créer de meilleurs projets
• Une meilleure collaboration en associant les concepteurs au processus de révision du code
• Quels podcasts les concepteurs et développeurs Web devraient-ils écouter ?
• Comment créer le CV de développeur Web parfait