Meilleures pratiques en matière d'examen du code

L'auteur bénéficie d'un point de vue différent sur sa tâche et sur son environnement. code. Ils apprendront souvent de nouvelles astuces ou découvriront une manière potentiellement plus optimale de résoudre un certain problème. Ils déploieront également leur ensemble de modifications en toute confiance, sachant que d'autres personnes ont vérifié l'exactitude du code et ont convenu que tout allait bien.

Le réviseur Il est avantageux de voir différentes approches de la résolution de problèmes en action. Ils amélioreront également leurs compétences en matière de lecture de code, ce qui est très important lorsqu'il s'agit de se plonger, par exemple, dans une bibliothèque dont l'utilisation est évaluée dans le cadre d'un projet de recherche. projet. L'examen du code est également une occasion d'apprentissage pour l'examinateur autant que pour l'auteur : ils peuvent également apprendre de nouvelles astuces.

Les équipe L'ensemble de l'équipe en bénéficie puisque l'examen d'une solution à un certain problème nécessite de comprendre le problème au moins à un niveau élevé d'abstraction. Cela permet d'éliminer les silos de connaissances accidentels qui peuvent se former au sein d'une équipe. Cela augmente également le "facteur bus" : étant donné qu'au moins deux personnes (de préférence plus) sont au courant d'un changement donné, il y a moins de risques que personne dans l'équipe ne sache comment mettre à jour un module, ou pourquoi un certain bogue peut se produire.

Le client bénéficie de changements et de solutions déployés rapidement et en toute confiance. Avec d'autres meilleures pratiques (telles qu'une grande couverture de test, CI/CD, des environnements de stockage, etc.), les revues de code garantissent également que ce qui est déployé est sûr, sain et répond aux exigences telles que spécifiées.

Intention et utilisation des présentes lignes directrices

N'oubliez pas que ces suggestions visent avant tout à créer un environnement propice à une résolution ambitieuse et efficace des problèmes, tout en créant un filet de sécurité et en encourageant la confiance et la transparence chez tous les membres de l'équipe.

Bien qu'il soit fortement suggéré qu'une équipe adhère à ces lignes directrices, celles-ci ne sont pas conçues comme des règles strictes et rigoureuses. Ce cadre n'est pas non plus conçu comme un "processus" à suivre à la lettre, car les processus rigides ont tendance à réduire la vitesse et à favoriser le gaspillage.

Vous pouvez tout à fait vous inspirer de ces lignes directrices au sein de votre équipe. N'oubliez pas, cependant, qu'au fur et à mesure que les développeurs changent d'équipe, ils s'attendront à ce que l'examen du code dans l'équipe qu'ils rejoignent soit toujours basé sur ce document. Conservez toutes les règles supplémentaires documentées et apportez à ce document les améliorations qui ont exceptionnellement bien fonctionné.

Responsabilités en matière d'examen du code

Chaque membre de l'équipe a certaines responsabilités en ce qui concerne l'examen du code. Ci-dessous, certaines choses à faire et à ne pas faire en matière de révision de code sont présentées en fonction du rôle dans le processus.

Chef de projet

• DO s'assurer que vos dépôts sont bien configurés (par exemple, les fusions vers votre branche de production ne sont pas autorisées sans au moins une révision d'approbation).
• DO veillez à ce que votre équipe comprenne et applique ces pratiques, et travaillez activement à promouvoir la compréhension des raisons pour lesquelles nous faisons les choses d'une certaine manière.
• DO Soyez attentif aux situations d'égalité, lorsque des opinions divergentes ne peuvent être résolues : en tant que responsable technique de votre équipe, il vous incombe de choisir la solution la plus pertinente dans de tels cas et de continuer à faire avancer le travail.
• Cependant, NE PAS utiliser la direction de projet comme un instrument contondant. NE PAS "pull rank". DO accueillir l'examen et la critique de vos solutions autant que vous l'encouragez pour le travail de quiconque.
• CONSIDEREZ l'ajout d'une intégration GitHub au canal Slack de votre équipe. Cela peut être utile pour mieux mettre les demandes de révision sur les radars des réviseurs, mais en fonction du volume global de votre canal, cela peut ou non convenir à votre équipe.

Membre de l'équipe

• Participez aux révisions de code. Il n'est pas acceptable de ne pas réviser le code.
• N'oubliez pas de faire vos revues de code : vos coéquipiers comptent sur vous pour faire avancer leur travail !
• Si vous ne pouvez absolument pas faire un certain examen, DO le communiquer clairement et ouvertement.
• Cependant, NE PAS supposer que vous ne pouvez pas effectuer un certain examen parce que vous ne connaissez pas ce module/ce côté du système/la spécification de la logique d'entreprise. L'examen du code est une occasion d'apprentissage importante.
• Si vous avez l'impression de ne pas en savoir assez sur un sujet pour en faire un compte rendu, DO demandez à l'auteur : il se fera un plaisir d'expliquer ce que les changements sont censés faire.
• NE PAS refuser les avis en fonction du niveau d'expérience (le vôtre) ou de l'auteur).
• DO essayez de réviser au moins autant de RP que vous en produisez. Dans l'idéal, le rapport entre le nombre de révisions données et le nombre de révisions requises doit être supérieur à 1 (en particulier dans les grandes équipes).

Auteur

• DO comprendre qu'il est de votre responsabilité de faire réviser votre code - votre équipe peut être proactivement à la recherche de requêtes à réviser, mais elle n'est pas obligée de le faire.
• NE PAS toujours assigner/demander des révisions aux mêmes membres de l'équipe - vous bénéficierez davantage d'un groupe de réviseurs variés (et inversement, un plus grand nombre de développeurs bénéficieront de la révision de votre code)
• NE PAS exclure quelqu'un de la révision sur la base de son expérience. Les développeurs juniors bénéficient de la révision du code. Les développeurs seniors bénéficient de la révision du code. Comme indiqué dans la préface de ce document, tout le monde bénéficie de l'examen du code.
• CONSIDERER l'utilisation d'un outil de sélection aléatoire pour choisir les évaluateurs. Par exemple, en Ruby, %w [coéquipier1 coéquipier2 coéquipier3].sample peut faire des merveilles.
• DO assignez au moins deux réviseurs à vos demandes de téléchargement, à moins que cela ne soit absolument impossible. De cette façon, plus de personnes bénéficient du processus (et avec trois personnes, il est plus difficile d'arriver à une égalité).
• DO Soyez réactif dans vos demandes d'extraction. Bien que vous ne deviez pas interrompre votre flux pour répondre immédiatement à tout commentaire, assurez-vous que vos réponses sont opportunes - sinon vos PRs s'attarderont indéfiniment dans la revue de code.
• DO adopter une attitude ouverte. Partez toujours du principe que votre examinateur essaie de vous aider avec les meilleures intentions du monde. Expliquez votre logique, répondez aux arguments de votre examinateur et à ses questions.
• DO être poli. Les malentendus sont fréquents, mais ils ne doivent pas devenir incontrôlables et nuire à l'ambiance au sein de l'équipe.
• DO être honnête. Si vous pensez qu'il s'agit de la meilleure solution, dites-le et présentez vos arguments. Si vous êtes convaincu que les suggestions de votre réviseur sont meilleures que ce que vous avez produit, dites-le-lui. Si vous pensez qu'une solution "meilleur des deux mondes" utilisant à la fois vos idées et celles de votre relecteur peut être produite, proposez-la leur. En fin de compte, travaillez à l'obtention d'un consensus dans vos pull requests.
• DO Laissez à votre réviseur le soin de résoudre leurs commentaires - ne vous contentez pas de les résoudre parce que vous êtes convaincu que tout va bien maintenant.
• DO expliquer activement votre tâche, votre raisonnement et d'autres exigences à vos évaluateurs. Il est acceptable de ne pas savoir, mais il n'est pas acceptable de ne pas savoir.
• NE PAS supposer que vous savez tout - nous sommes tous d'excellents spécialistes, mais il est important de faire preuve d'une certaine humilité lorsque vous travaillez avec vous.
• DO être le premier évaluateur de votre code. Portez un chapeau d'examinateur et scrutez soigneusement le code comme vous le feriez pour la personne que vous n'aimez pas le plus. Identifiez et éliminez les éléments les plus évidents, comme les lignes vides, les restes ou les spécifications manquantes. Ne sautez rien - il est fort probable qu'on vous le signalera de toute façon. Ne faites pas perdre de temps aux évaluateurs !
• DO Décrivez minutieusement votre pull request. La description est bonne lorsque l'évaluateur ne sera pas surpris par quoi que ce soit en lisant le code. Rappelez-vous qu'il ne peut pas lire dans vos pensées. C'est pourquoi il est important de décrire les choses qui ne sont pas évidentes, les décisions clés avec la raison ou toutes les nouvelles classes et fichiers.
• CONSIDERER en utilisant le modèle de demande d'extraction. Si vous utilisez Github, ajoutez-le à votre dépôt sous .github/pull_request_template.md. Cela encourage tous les membres de l'équipe à décrire leurs pull requests. Il est également beaucoup plus facile d'écrire lorsque le champ de description est rempli avec un modèle. Voici un modèle que nous utilisons dans l'un de nos projets https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Auteur

• DO comprendre qu'il est de votre responsabilité d'avoir votre examen du code - votre équipe recherche peut-être de manière proactive des demandes de téléchargement à examiner, mais elle n'est pas obligée de le faire.
• NE PAS toujours assigner/demander des examens au même les réviseurs de code - vous bénéficierez davantage d'un pool d'évaluateurs varié (et inversement, un plus grand nombre de développeurs bénéficieront de l'évaluation de votre code)
• NE PAS exclure quelqu'un de l'examen sur la base de son expérience. Les développeurs juniors bénéficient de l'exécution examen du code. Les développeurs seniors bénéficient de l'exécution examen du code. Comme indiqué dans la préface de ce document, tout le monde les avantages de l'exécution examen du code.

Réviseur

• DO utiliser le langage de la suggestion plutôt que celui de l'exigence. Au lieu de dire "Vous devriez améliorer la qualité du code en faisant X à la place"dire "Avez-vous envisagé d'améliorer qualité du code en faisant X ?"
• DO expliquer vos suggestions. "Je pense que le X est meilleur ici parce qu'il aide à transfert de connaissances et améliorer la qualité du code."
• Même si votre suggestion provient de sources objectives (par ex. style de code ), DO demander à l'auteur de faire quelque chose au lieu de lui dire de faire quelque chose. "Veuillez garder tous les widgets frobnicated conformément à notre style de code guide - [lien]"
• NE PAS supposer que vous savez tout. "J'ai cru comprendre que ce widget ne devrait jamais geler, et dans ces conditions, il le fera - s'agit-il d'une exception qui nécessite une autorisation ? examen du code?"
• DO utiliser un langage inclusif. "Je pense que nous serions mieux lotis à l'avenir si nous construisions ce projet de cette manière. Qu'en pensez-vous ? un meilleur examen du code suggestion ?" et "Peut-être devrions-nous plutôt utiliser X ici pour un un examen efficace du code?"
• DO être rapide dans l'accomplissement de vos examen du code. Vous ne devez pas interrompre votre flux pour les faire, mais essayez de garder la boucle serrée si possible. Certaines personnes aiment les faire au début ou à la fin de leur journée de travail, en guise d'"échauffement" ou de "récupération".

Veuillez noter que ces mots-clés ont été insérés de manière à préserver le contexte et la cohérence du texte. Si vous souhaitez qu'ils soient insérés à des endroits spécifiques, veuillez le préciser.