En ce qui concerne l'inspection du code, l'attention des gens est généralement concentrée sur qui le fait. Mais le développeur qui a écrit le code joue un rôle tout aussi important dans le processus que le réviseur. Il n'y a presque pas de recommandations pour préparer le code pour l'inspection, de sorte que les auteurs font souvent des erreurs simplement par ignorance.
Cet article compile les meilleures pratiques pour participer à l'inspection de code en tant qu'auteur. Lorsque vous aurez fini de lire, vous commencerez à envoyer aux inspecteurs des ensembles de changements si parfaits qu'ils brûleront d'amour pour vous, rien de moins.
Mais je ne veux pas que les inspecteurs de code brillent d'amour pour moi
Et ils le seront toujours. Humiliez-vous. Personne dans l'histoire de l'humanité ne s'est encore plaint sur son lit de mort d'avoir été trop aimé de son vivant.
Pourquoi améliorer l'inspection du code?
L'apprentissage de techniques d'inspection efficaces facilitera la vie de l'inspecteur, de l'équipe et, surtout, de vous.
- Processus de transfert de connaissances accéléré. Si vous préparez correctement votre ensemble de modifications, l'attention de l'inspecteur sera attirée sur les domaines dans lesquels vous devez vous développer, plutôt que sur des défauts stylistiques ennuyeux. Et lorsque vous indiquez clairement que vous appréciez la critique constructive, le réviseur commence à consacrer plus d'efforts à la rétroaction.
- Un exemple pour les autres. Les bonnes pratiques d'inspection du code dans vos performances établiront la barre pour ceux qui vous entourent. De bonnes techniques sont généralement adoptées, ce qui signifie que ce sera plus facile pour vous lorsqu'un collègue vous envoie du code pour examen.
- Conflits minimaux. L'inspection du code crée souvent des tensions dans l'équipe. Si vous abordez la question de manière responsable et délibérée, les différends surviendront moins souvent.
Règle d'or: valoriser le temps du critique
Cela semble évident, mais je rencontre souvent des auteurs qui traitent les inspecteurs comme leurs propres spécialistes du contrôle de la qualité. Ces personnes ne frapperont pas du doigt pour détecter au moins certaines des erreurs ou pour effectuer un ensemble de modifications pratiques pour la vérification.
Vos collègues viennent travailler tous les jours avec une attention limitée. S'ils vous en consacrent une partie, ils ne peuvent plus dépenser cette ressource pour leurs propres tâches. Tirer le meilleur parti de son temps est une simple question de justice.
La révision du code est beaucoup plus réussie lorsque les participants peuvent se faire confiance. Votre inspecteur ne ménagera aucun effort s'il sait que vous prendrez ses remarques au sérieux. Si vous percevez l'examinateur comme un obstacle à surmonter, vous recevrez de sa part des recommandations beaucoup moins précieuses.
Technique
1. Vérifiez vous-même le code
avant d'envoyer le code à un collègue, lisez-le. Ne vous limitez pas à attraper des erreurs - imaginez voir ce fragment pour la première fois. Qu'est-ce qui peut être déroutant?
D'après mon expérience, il peut être utile de faire une pause entre l'écriture et l'édition du code. Les gens envoient souvent un nouveau code à la fin de la journée, mais c'est pendant cette période qu'ils risquent le plus de manquer quelque chose par négligence. Attendez jusqu'au matin, jetez un regard neuf sur l'ensemble des modifications, puis transmettez-le à un collègue.
Quel idiot a écrit ça?
Synchronisation des tâches Cron avec le cycle lunaire: j'ai ajouté une logique synchronisée pour garder notre
pipeline ETL en phase avec la nature. Simulez autant que possible l'environnement de travail d'un validateur. Utilisez le même utilitaire de comparaison que lui. Les bogues stupides se trouvent mieux dans ces utilitaires que dans votre éditeur de code habituel.
Ne vous attendez pas à être parfait. Vous allez inévitablement envoyer le code avec un morceau que vous avez oublié de supprimer après avoir corrigé un bogue, ou un fichier errant que vous alliez supprimer. Ce n'est pas la fin du monde, mais cela vaut toujours la peine d'être suivi. Notez les modèles dans vos erreurs et déterminez quels systèmes vous pouvez mettre en œuvre pour les éviter. Si les mêmes erreurs passent très souvent, l'inspecteur conclura que vous n'appréciez pas son temps.
2. Rédigez une description claire du jeu de modifications
Dans mon dernier travail de mentorat, j'ai eu des rencontres occasionnelles avec un programmeur plus expérimenté. Avant la première réunion, il m'a demandé de récupérer un document de conception de logiciel que j'avais compilé. En lui remettant les papiers, j'ai expliqué en quoi consistait le projet et en quoi il était lié aux objectifs de mon équipe. Mon mentor fronça les sourcils et dit sans détour: "Tout ce que vous venez de dire devrait être sur la première page du document."
Et il avait raison. J'ai écrit le document avec l'attente des développeurs de mon équipe, mais je n'ai pas tenu compte du fait qu'il pourrait être lu par des étrangers. Le public ne se limitait pas aux limites de mon département - il y avait encore des équipes partenaires, des mentors, des personnes qui prenaient des décisions sur les promotions... Le document aurait dû être rédigé pour que tout soit clair pour eux. Après cette conversation, j'essaye toujours de présenter mon travail dans le contexte nécessaire à la compréhension.
La description de l'ensemble de modifications doit inclure toutes les informations de base dont le lecteur pourrait avoir besoin. Même si vous rédigez la description pour le bien de l'examinateur, gardez à l'esprit qu'il peut avoir moins d'informations contextuelles que vous ne le pensez. En outre, il est possible que d'autres collègues devront également travailler avec ce code à l'avenir - lorsqu'ils examinent l'historique des modifications, ils doivent comprendre vos intentions.
Une bonne description décrit à quoi sert l'ensemble de modifications et pourquoi vous avez choisi d'agir de cette manière.
Si vous voulez vous plonger plus profondément dans l'art d'écrire de grandes descriptions, lisez « Comment écrire un message de validation Git » de Chris Beams et « Mon commit Git préféré » de David Thompson.
3. Automatisez des choses simples
Si vous comptez sur l'inspecteur pour des petites choses comme une attelle flottante ou des problèmes avec des tests automatisés, alors vous perdez son temps.
Vérifiez si tout est en ordre avec la syntaxe? Je me tournerais vers le compilateur, mais c'est dommage de perdre son temps.
Les tests automatisés doivent être considérés comme faisant partie de la procédure standard dans le cadre de l'équipe. L'inspection ne commence que lorsque toute la série de contrôles automatisés dans un environnement d'intégration continue a été réussie .
Si votre équipe est tragiquement délirante et rejette l'intégration continue, mettez en place un examen automatisé en interne. Implémentez des hooks , des linters et des formateurs de pré-validation dans votre environnement de développement pour vous assurer que toutes les conventions sont respectées et que le comportement prévu persiste d'une validation à l'autre.
4. Assurez-vous que le code lui-même répond aux questions
Qu'est-ce qui ne va pas avec cette image?
Je ne comprends pas le but de la fonction.
Et, c'est au cas où le Frombobulator est passé pendant l'appel en l'absence d'implémentation frombobulate L'
auteur m'a aidé à comprendre la fonction, mais qu'en est-il du lecteur suivant? Creuser dans l'histoire des changements et relire toutes les discussions? C'est encore pire quand l'auteur vient à mon bureau pour tout expliquer en personne. Premièrement, cela m'empêche de me concentrer, et deuxièmement, aucune âme vivante n'aura plus accès aux informations sonores.
Lorsque l'inspecteur exprime de la confusion sur un point du code, votre travail n'est pas de clarifier la situation pour cette personne en particulier. Il est nécessaire de clarifier la situation pour tout le monde à la fois.
- Bonjour?
- Quand vous avez écrit bill.py il y a six ans, pourquoi aviez-vous t = 6?
- Content que vous ayez appelé! Cela est dû à la taxe de vente de 6%.
- Bien sûr!
- Un excellent moyen de justifier une décision de mise en œuvre.
La meilleure réponse à toute question est la refactorisation du code qui le supprime. Que peut-on renommer pour clarifier comment changer la logique? Les commentaires sont une solution acceptable, mais ils jouent certainement dans le contexte d'un code qui se documente naturellement.
5. Saisissez les modifications de manière fractionnée
Répandre les limites est une mauvaise pratique et peut souvent être observée lors de l'inspection du code. Le développeur s'engage à corriger un bogue dans la logique, mais en cours de route, il rencontre une faille dans l'interface. "Et bien, puisque je travaille avec ce morceau de toute façon," pense-t-il, "je vais le réparer en même temps." En conséquence, la confusion commence. Le réviseur devra maintenant déterminer quels changements fonctionnent pour la tâche A et lesquels fonctionnent pour la tâche B.
Les meilleurs ensembles de modifications font une chose . Plus le changement est précis et simple, plus il est facile pour l'inspecteur de garder le contexte à l'esprit. En partageant des modifications non liées, vous avez également la possibilité de faire examiner plusieurs pairs en parallèle, ce qui signifie que votre code vous reviendra plus rapidement.
6.
Changements fonctionnels et non fonctionnels séparés Une autre règle de base est que les changements fonctionnels et non fonctionnels ne doivent pas être confondus.
Les développeurs ayant peu d'expérience avec l'inspection de code enfreignent souvent cette règle. Ils apportent une sorte de changement de ventilation, et l'éditeur de code change immédiatement le format dans tout le fichier. Le développeur ne comprend pas ce qui s'est passé, ou décide que c'est encore mieux et envoie le code, où un changement fonctionnel est enfoui sous des centaines de lignes avec des non fonctionnelles.
Trouverez-vous un changement fonctionnel?
Une telle confusion est comme une salive face à un inspecteur. Les modifications de format uniquement sont faciles à vérifier. Des changements fonctionnels aussi. Une panne fonctionnelle dans un océan de changements de format peut être vaine et folle.
De plus, les développeurs aiment mélanger le refactoring en changements majeurs en temps opportun. J'approuve fortement la refactorisation du code par mes collègues, mais pas lorsqu'ils implémentent simultanément un nouveau comportement.
Changement de comportement enterré au milieu de la refactorisation
Si un morceau de code nécessite à la fois une refactorisation et des changements de comportement, vous devez diviser le processus en deux ou trois ensembles:
- Ajouter des tests pour le comportement actuel (s'il n'y en a pas)
- Refactoriser le code sans rien changer dans les tests
En gardant les tests intacts dans la deuxième étape, le réviseur peut s'assurer que la refactorisation ne perturbe pas le comportement. En conséquence, à la troisième étape, il n'aura pas à comprendre ce qui est refactorisé ici, et ce qui fonctionne pour changer le comportement - après tout, vous avez séparé l'un de l'autre à l'avance.
7. Briser les changesets trop volumineux Les
changesets gonflés sont comme les vilains cousins des frontières tentaculaires . Imaginez une situation: un développeur arrive à la conclusion que pour implémenter la fonctionnalité A, il devra d'abord corriger la sémantique des bibliothèques B et C.S'il y a peu de changements, alors quoi qu'il arrive, mais très souvent ces modifications s'étalent et une énorme liste de changements est produite.
La complexité du journal des modifications augmente de façon exponentielle avec le nombre de lignes affectées. Si les modifications concernent 400 lignes ou plus, je cherche un moyen de les couper avant de demander une inspection.
Peut-être qu'au lieu de tout faire en même temps, il sera possible de travailler d'abord avec les dépendances, et dans le prochain ensemble, d'implémenter de nouvelles fonctionnalités? Est-il réaliste de garder le code sain si vous implémentez la moitié de la fonctionnalité maintenant et l'autre moitié dans la phase suivante?
Réfléchir à la façon de décomposer le code pour obtenir une pièce intelligible et fonctionnelle peut être fastidieux. Mais cela permet une meilleure rétroaction et crée moins de complexité pour le réviseur.
8. Acceptez les critiques avec bonté
Le moyen le plus sûr de gâcher tout le test est de prendre la critique avec hostilité. Il peut être difficile de résister, car de nombreux développeurs sont fiers de ce qu'ils font et perçoivent leur travail comme une extension d'eux-mêmes. Et si l'inspecteur fait des commentaires sans tact ou s'adresse à une personne , cela complique encore davantage la situation.
En fin de compte, vous, en tant qu'auteur, êtes libre de décider comment vous répondez aux commentaires. Traitez les propos de l'inspecteur comme une discussion objective du code qui n'a rien à voir avec l'évaluation de votre personnalité. Si vous êtes sur la défensive, cela ne fait qu'empirer.
J'essaie de prendre tous les commentaires comme une tentative d'aider et de bénéficier. Si le critique trouve une erreur stupide dans le code, je suis instinctivement amené à commencer à trouver des excuses. Mais je me retiens et loue plutôt son observation.
- Pour janvier et février 1900, cela ne fonctionnera pas.
- Exactement, bien remarqué!
Curieusement, le fait que l'inspecteur détecte des failles non évidentes dans le code est un bon signe. Cela suggère que vous êtes doué pour préparer les fichiers à analyser. En l'absence de mise en forme bâclée, de mauvais noms et d'autres choses remarquables, le critique peut étudier la logique et la conception en profondeur et faire des observations plus précieuses.
9. Soyez patient si l'inspecteur fait une erreur
De temps en temps, il arrive que l'inspecteur se trompe tout simplement. Il peut mal lire du code parfaitement normal aussi bien que vous pouvez planter des bogues. De nombreux développeurs dans de tels cas commencent à se défendre farouchement. Ils sont offensés que quelqu'un soumette leur travail à des critiques, et même ne soit basé sur rien.
Cependant, même si le critique se trompe, vous avez encore beaucoup à penser. S'il a mal lu quelque chose, quelle est la probabilité que d'autres personnes commettent la même erreur à l'avenir? Les lecteurs n'auraient-ils pas à étudier le code dans les deux sens, juste pour s'assurer que le bogue qu'ils voient n'est pas là?
- Il y a un débordement de tampon ici, car aucune vérification n'a été effectuée pour savoir s'il y a suffisamment de mémoire dans le nom pour accueillir tous les caractères NewNameLen.
- Est-ce dans mon code? Impensable! Le constructeur appelle PurchaseHats, et il appelle CheckWeather, ce qui lèverait une erreur si la longueur du tampon ne correspond pas. Vous liriez d'abord 200 000 lignes de code, puis vous oseriez admettre la possibilité que je me sois trompé quelque part.
Réfléchissez à la façon de refactoriser ou d'ajouter des commentaires pour que, d'un coup d' œil, vous puissiez voir que tout est en ordre. Si le malentendu provient de l'utilisation de fonctionnalités peu connues du langage, réécrivez le code en utilisant des mécanismes qui ne nécessitent pas de connaissances approfondies.
10. Donner une réaction intelligible
Je me retrouve souvent dans cette situation: j'envoie des commentaires à une personne, il met à jour le code en tenant compte de certains d'entre eux, mais en même temps reste silencieux. Il y a une période d'incertitude. Soit il a manqué le reste des commentaires, soit il est toujours en train de corriger. Si vous commencez à vérifier ce qui a déjà été fait, hypothétiquement, il se peut que ce morceau de code soit toujours en cours de travail et que je perds mon temps. Si nous attendons, nous pouvons entrer dans une impasse - nous allons tous les deux nous asseoir et attendre la prochaine étape l'un de l'autre.
Établissez un certain ordre des actions dans l'équipe afin que l'on sache toujours qui a le «témoin» en ce moment. Le processus ne devrait pas être autorisé à ralentir simplement parce que personne ne comprend ce qui se passe. C'est facile à faire - il suffit de laisser des commentaires au niveau de l'ensemble de modifications, à partir duquel il est clair quand le droit d'agir est transféré à un autre participant.
Corriger les en-têtes> Mettre à jour le code en fonction des commentaires> Tout est prêt, veuillez regarder.
Tout commentaire qui vous oblige à prendre des mesures doit être répondu en confirmant que vous l'avez pris. Certains outils d'inspection de code permettent de signaler les commentaires traités. Sinon, utilisez un ensemble de puces de texte simples comme Terminé. Si vous n'êtes pas d'accord avec le commentaire, expliquez poliment pourquoi vous avez décidé de vous abstenir de corriger.
Certains outils comme Reviewable et Gerritt suggèrent de baliser les commentaires traités
. Équilibrez vos réactions par rapport aux efforts du réviseur. S'il a détaillé un moment pour que vous puissiez apprendre quelque chose de nouveau par vous-même, ne vous limitez pas à la marque «Terminé». Répondez attentivement pour montrer que vous appréciez son travail.
11. Solliciter habilement les informations manquantes
Parfois, les commentaires de l'inspecteur laissent trop de place à l'interprétation. Lorsqu'ils vous écrivent quelque chose dans l'esprit «Je ne comprends pas cette fonction», la question se pose immédiatement, ce qui n'est pas clair pour une personne. Trop long? Le nom est-il malheureux? Besoin de mieux documenter?
Pendant longtemps, je me suis demandé comment clarifier des commentaires vagues et ne pas entrer par inadvertance dans la confrontation. La première chose qui m'est venue à l'esprit a été de demander: «Qu'est-ce qui est incompréhensible en elle?», Mais cela semble grincheux.
Une fois, j'ai délibérément envoyé une vague réponse à ce genre de collègue, et il m'a désarmé avec sa réponse:
"Qu'est-ce qui peut être changé pour l'améliorer?"
J'aime cette phrase car elle exprime une ouverture à la critique et un manque d'hostilité. Maintenant, lorsque j'obtiens de vagues commentaires, je réponds avec une variation du motif de base "Que peut-on changer pour l'améliorer?"
Une autre technique utile consiste à essayer de deviner ce que le réviseur voulait dire et à prendre les devants en corrigeant le code en conséquence. Si vous obtenez un commentaire "incompréhensible", regardez de plus près le code. On trouve généralement quelque chose qui peut être amélioré en termes de clarté. Les modifications indiquent à l'inspecteur que vous êtes prêt à apporter des modifications, même s'il avait une idée différente du résultat final.
12. Donner la priorité à l'examinateur
Au tennis, s'il n'est pas tout à fait clair si le ballon est sorti des limites lors du service de l'adversaire, il est d'usage d'interpréter la situation en sa faveur. Cette règle doit également être suivie lors de l'inspection de votre code.
Certaines décisions de conception sont une question de goût. Si le critique pense que votre fonction de dix lignes serait mieux divisée en deux fonctions de cinq lignes, la vérité objective n'est ni la vôtre ni la sienne. La meilleure option dépend de la préférence.
Si l'inspecteur fait une proposition et que les arguments à l'appui de sa position sont à peu près égaux pour vous, acceptez son point de vue. Après tout, de vous deux, c'est lui qui profite d'un nouveau regard sur le code.
13. Réduisez le temps de transfert de code
Il y a quelques mois, un utilisateur a apporté une petite modification à un projet open source que je maintiens. Je me suis désabonné avec des commentaires quelques heures plus tard, mais il a déjà disparu avec les extrémités. Quelques jours plus tard, je suis revenu et j'ai constaté qu'il n'y avait toujours pas de réponse.
Six semaines se sont écoulées et le mystérieux développeur est réapparu sur le projet avec des révisions. Bien que j'apprécie son travail, la longue pause entre les deux étapes de vérification a conduit au fait que j'ai consacré deux fois plus d'efforts à l'inspection. J'ai dû relire non seulement le code, mais aussi mes propres commentaires afin de me souvenir de ce qui était généralement discuté. Si la personne se présentait dans quelques jours, il n'y aurait pas besoin de travail supplémentaire.
Coûts intellectuels pour l'inspection de code avec des temps de transmission courts (à gauche) et longs (à droite)
L'axe des x est le temps; axe y - mémoire de l'inspecteur; ombrage bleu - restauration du contexte; remplissage bleu - vérification du code; remplissage gris - en attente; ombrage rouge - coûts supplémentaires
Six semaines est, bien entendu, un cas exceptionnel, mais je constate souvent de longues pauses injustifiées dans mon équipe. Quelqu'un soumet un ensemble de modifications pour examen, obtient des commentaires et reporte les modifications d'une semaine parce qu'il a été distrait par une autre tâche.
Outre le fait que vous devez passer du temps à récupérer le contexte plus tard, les fragments de code semi-finis créent de la complexité. Ils rendent plus difficile le suivi de ce qui est déjà drainé et de ce qui ne l'est pas encore. Plus les listes de modifications partiellement traitées sont créées, plus la probabilité de conflits de fusion est élevée et personne n'aime les manipuler.
Une fois que vous avez soumis votre code pour inspection, votre priorité absolue est de le suivre. Si le processus stagne par votre faute, vous volez le temps de l'inspecteur et compliquez la vie de toute l'équipe.
finalement
Lorsque vous préparez votre prochain journal des modifications à soumettre, réfléchissez aux facteurs que vous pouvez traiter et utilisez ces opportunités pour rendre la révision productive. Lorsque vous participez à une révision de code, vérifiez les éléments qui ralentissent régulièrement le processus et gaspillent des ressources.
N'oubliez pas la règle d'or: valorisez le temps du critique. Si vous lui donnez l'occasion de se concentrer sur les parties vraiment intéressantes du code, ses commentaires seront utiles. Si vous le forcez à perdre du temps sur de petites choses ou à démêler la confusion, tant pis pour vous deux.
Enfin, réfléchissez bien à vos réponses. Des malentendus sur des bagatelles ou des mots irréfléchis peuvent faire dérailler les choses à une vitesse alarmante. Les passions sont vives lorsqu'il s'agit de critiquer le travail de quelqu'un d'autre, alors évitez soigneusement tout ce qui pourrait amener l'examinateur à penser que vous l'attaquez ou que vous le traitez sans respect.
Toutes nos félicitations! Si vous avez lu jusqu'ici, vous pouvez déjà vous considérer comme un expert en inspection de code. Vos inspecteurs sont probablement déjà en feu, vous les traitez donc humainement.