Comment trouver des choses positives dans une revue de code?
Après de sérieux problèmes de qualité au cours de la dernière année, mon entreprise a récemment introduit des révisions de code. Le processus de révision du code a été rapidement introduit, sans lignes directrices ni liste de contrôle.
Un autre développeur et moi avons choisi d'examiner toutes les modifications apportées aux systèmes, avant qu'elles ne soient fusionnées dans le coffre.
Nous avons également été choisis comme "Lead technique". Cela signifie que nous sommes responsables de la qualité du code, mais nous n'avons aucune autorité pour mettre en œuvre des changements dans le processus, réaffecter des développeurs ou bloquer des projets.
Techniquement, nous pouvons refuser la fusion, la redonner au développement. En réalité, cela se termine presque toujours avec notre patron exigeant qu'il soit expédié à temps.
Notre gestionnaire est un MBA qui se préoccupe principalement de créer un calendrier des projets à venir. Pendant qu'il essaie, il n'a presque aucune idée de ce que fait notre logiciel d'un point de vue commercial et a du mal à comprendre même les demandes les plus élémentaires des clients sans l'explication d'un développeur.
Actuellement, le développement se fait dans les branches de développement de SVN, après que le développeur pense qu'il est prêt, il réattribue le ticket dans notre système de billetterie à notre responsable. Le gestionnaire nous l'assigne ensuite.
Les révisions de code ont conduit à des tensions au sein de notre équipe. En particulier, certains des membres plus âgés remettent en question les changements (c'est-à-dire "Nous l'avons toujours fait comme ça" ou "Pourquoi la méthode devrait-elle avoir un nom raisonnable, je sais ce qu'elle fait?").
Après les premières semaines, ma collègue a commencé à laisser les choses glisser, pour ne pas causer de problèmes aux collègues (elle m'a dit elle-même qu'après qu'un rapport de bug a été déposé par un client, elle était au courant du bug, mais craignait que le développeur serait en colère contre elle pour l'avoir souligné).
Moi, d'autre part, je suis maintenant connu pour être un âne pour signaler les problèmes avec le code validé.
Je ne pense pas que mes normes soient trop élevées.
Ma liste de contrôle en ce moment est:
- Le code se compilera.
- Il existe au moins une façon dont le code fonctionnera.
- Le code fonctionnera avec la plupart des cas normaux.
- Le code fonctionnera avec la plupart des cas Edge.
- Le code lèvera une exception raisonnable si les données insérées ne sont pas valides.
Mais j'accepte pleinement la responsabilité de la façon dont je donne des commentaires. Je donne déjà des points exploitables expliquant pourquoi quelque chose devrait être changé, parfois même en demandant simplement pourquoi quelque chose a été mis en œuvre d'une manière spécifique. Quand je pense que c'est mauvais, je précise que je l'aurais développé d'une autre manière.
Ce qui me manque, c'est la capacité de trouver quelque chose à signaler comme "bon". J'ai lu qu'il fallait essayer de prendre en sandwich les mauvaises nouvelles et les bonnes nouvelles.
Mais j'ai du mal à trouver quelque chose de bien. "Hé cette fois, vous avez réellement commis tout ce que vous avez fait" est plus condescendant que Nice ou utile.
Exemple de révision du code
Salut Joe,
J'ai des questions sur vos modifications dans la classe Library\ACME\ExtractOrderMail.
Je ne comprenais pas pourquoi vous avez marqué "TempFilesToDelete" comme statique? Pour le moment, un deuxième appel à "GetMails" lèverait une exception, car vous y ajoutez des fichiers mais ne les supprimez jamais, après les avoir supprimés. Je sais que la fonction est appelée une seule fois par exécution, mais à l'avenir, cela pourrait changer. Pourriez-vous simplement en faire une variable d'instance, alors nous pourrions avoir plusieurs objets en parallèle.
... (Quelques autres points qui ne fonctionnent pas)
Points mineurs:
- Pourquoi "GetErrorMailBody" prend une exception comme paramètre? Ai-je oublié quelque chose? Vous ne lancez pas l'exception, vous la transmettez simplement et appelez "ToString". Pourquoi donc?
- SaveAndSend n'est pas un bon nom pour la méthode. Cette méthode envoie des e-mails d'erreur si le traitement d'un courrier a échoué. Pourriez-vous le renommer en "SendErrorMail" ou quelque chose de similaire?
- Veuillez ne pas simplement commenter l'ancien code, supprimez-le carrément. Nous l'avons toujours dans Subversion.
Comment trouver des choses positives dans une revue de code?
Après de sérieux problèmes de qualité au cours de la dernière année, mon entreprise a récemment introduit des révisions de code.
Super, vous avez une réelle opportunité de créer de la valeur pour votre entreprise.
Après les premières semaines, ma collègue a commencé à laisser les choses glisser, pour ne pas causer de problèmes aux collègues (elle m'a dit elle-même qu'après qu'un rapport de bug a été déposé par un client, elle était au courant du bug, mais craignait que le développeur serait en colère contre elle pour l'avoir souligné).
Votre collègue ne devrait pas faire de révision de code si elle ne parvient pas à dire aux développeurs ce qui ne va pas avec leur code. C'est votre travail trouver les problèmes et les résoudre avant ils affectent les clients.
De même, un développeur qui intimide ses collègues de travail demande à être licencié. Je me suis senti intimidé après une révision du code - je l'ai dit à mon patron, et cela a été géré. De plus, j'aime mon travail, j'ai donc gardé le feedback positif et négatif. En tant que critique, c'est sur moi, sur personne d'autre.
Moi, d'autre part, je suis maintenant connu pour être un âne pour signaler les problèmes avec le code validé.
Eh bien, c'est dommage, vous dites que vous faites preuve de tact. Vous pouvez trouver plus à louer, si vous avez plus à chercher.
Critiquer le code, pas l'auteur
Vous donnez un exemple:
J'ai des questions sur vos changements dans
Évitez d'utiliser les mots "vous" et "votre", disons "les" changements à la place.
Ai-je oublié quelque chose? [...] Pourquoi donc?
N'ajoutez pas de fioritures rhétoriques à vos critiques. Ne faites pas de blagues non plus. Il y a une règle que j'ai entendue: "Si ça vous fait du bien de le dire, ne le dites pas, ce n'est pas bon."
Peut-être que vous polissez votre propre ego aux frais de quelqu'un d'autre. Restez fidèle aux faits.
Élevez la barre en donnant des commentaires positifs
Cela élève la barre pour féliciter vos collègues développeurs lorsqu'ils répondent à des normes plus élevées. Cela signifie donc que la question,
Comment trouver des choses positives dans une revue de code?
est bon et mérite d'être abordé.
Vous pouvez indiquer où le code rencontre les idéaux des pratiques de codage de niveau supérieur.
Recherchez-les pour suivre les meilleures pratiques et continuer à élever la barre. Une fois que les idéaux les plus faciles seront attendus de tout le monde, vous voudrez cesser de les louer et rechercher de meilleures pratiques de codage pour les louanges.
Meilleures pratiques spécifiques à la langue
Si le langage prend en charge la documentation dans le code, les espaces de noms, les fonctionnalités de programmation orientées objet ou fonctionnelles, vous pouvez les appeler et féliciter l'auteur de les avoir utilisées le cas échéant. Ces questions relèvent généralement de guides de style:
- Répond-il aux normes du guide de style de langage interne?
- Répond-il au guide de style le plus fiable pour la langue (qui est probablement plus strict qu'en interne - et donc toujours conforme au style interne)?
Meilleures pratiques génériques
Vous pouvez trouver des points à louer sur les principes de codage génériques, sous divers paradigmes. Par exemple, ont-ils de bons tests? Les unittests couvrent-ils la majeure partie du code?
Chercher:
- tests unitaires qui testent uniquement la fonctionnalité du sujet - se moquant de fonctionnalités coûteuses qui ne sont pas destinées à être testées.
- des niveaux élevés de couverture de code, avec des tests complets des API et des fonctionnalités sémantiquement publiques.
- des tests d'acceptation et des tests de fumée qui testent la fonctionnalité de bout en bout, y compris la fonctionnalité qui est simulée pour les tests unitaires.
- bonne dénomination, points de données canoniques donc le code est DRY (ne vous répétez pas), pas de chaînes ou de nombres magiques.
- nom de variable si bien fait que les commentaires sont en grande partie redondants.
- nettoyages, améliorations objectives (sans compromis) et remaniements appropriés qui réduisent les lignes de code et la dette technique sans rendre le code complètement étranger aux rédacteurs originaux.
Programmation fonctionnelle
Si le langage est fonctionnel ou prend en charge le paradigme fonctionnel, recherchez ces idéaux:
- éviter les globaux et l'état global
- utilisant des fermetures et des fonctions partielles
- petites fonctions avec des noms lisibles, corrects et descriptifs
- points de sortie uniques, minimisant le nombre d'arguments
Programmation orientée objet (POO)
Si la langue prend en charge la POO, vous pouvez louer l'utilisation appropriée de ces fonctionnalités:
- encapsulation - fournit une interface publique clairement définie et petite, et masque les détails.
- héritage - code réutilisé de manière appropriée, peut-être par le biais de mixins.
- polymorphisme - les interfaces sont définies, peut-être des classes de base abstraites, des fonctions écrites pour supporter le polymorphisme paramétrique.
sous OOP, il y a aussi SOLIDES principes (peut-être une certaine redondance pour OOP fonctionnalités):
- responsabilité unique - chaque objet a un intervenant/propriétaire
- ouvert/fermé - ne modifie pas l'interface des objets établis
- Substitution de Liskov - des sous-classes peuvent être substituées aux instances de parents
- ségrégation d'interfaces - interfaces fournies par la composition, peut-être des mixins
- inversion de dépendances - interfaces définies - polymorphisme ...
Programmation Unix principes :
Les principes Unix sont la modularité, la clarté, la composition, la séparation, la simplicité, la parcimonie, la transparence, la robustesse, la représentation, la moindre surprise, le silence, la réparation, l'économie, la génération, l'optimisation, la diversité et l'extensibilité.
En général, ces principes peuvent être appliqués dans de nombreux paradigmes.
Vos critères
Celles-ci sont beaucoup trop triviales - je me sentirais condescendu si je les louais pour cela:
- Le code se compilera.
- Il existe au moins une façon dont le code fonctionnera.
- Le code fonctionnera avec la plupart des cas normaux.
D'un autre côté, ce sont des éloges assez élevés, compte tenu de ce que vous semblez avoir à faire, et je n'hésiterais pas à féliciter les développeurs pour cela:
- Le code fonctionnera avec la plupart des cas Edge.
- Le code lèvera une exception raisonnable si les données insérées ne sont pas valides.
Écrire des règles pour passer la révision du code?
C'est une excellente idée en théorie, cependant, bien que je ne rejette généralement pas le code pour une mauvaise dénomination, j'ai vu une dénomination si mauvaise que je rejetterais le code avec des instructions pour le corriger. Vous devez être en mesure de rejeter le code pour une raison quelconque.
La seule règle à laquelle je peux penser pour rejeter du code est qu'il n'y a rien de si flagrant que je le garderais hors de production. Une très mauvaise réputation est quelque chose que je serais prêt à garder hors de la production - mais vous ne pouvez pas en faire une règle.
Conclusion
Vous pouvez louer les meilleures pratiques suivies sous plusieurs paradigmes, et probablement sous tous, si le langage les prend en charge.
Ne vous embêtez pas à choisir quelque chose de bien à moins que ce soit un exemple concis solide et directement lié au problème ciblé.
Je ne l'enroberai pas - à en juger par les sons, vous avez affaire à au moins une personne qui n'est pas sûre de ses capacités et gère les défis de son travail de manière immature. Ils sont également probablement mauvais dans leur travail - un bon développeur doit toujours être prêt à réfléchir, à prendre des critiques constructives et à être ouvert à changer ses manières.
Maintenant que c'est dans l'air, parlons de vous. Peu importe si vous pensez que vous êtes raisonnable, vous devez être très prudent avec des gens comme celui-ci pour faire bouger les choses. J'ai trouvé que la meilleure façon de traiter avec ces gens est de faire très attention à la façon dont vous parlez des choses.
Assurez-vous que vous blâmez le code et non l'auteur. Concentrez-vous sur le problème en question plutôt que sur la montagne de caca qui est votre base de code, qu'ils ont peut-être joué un rôle important dans la création et seraient considérés comme une nouvelle attaque personnelle. Choisissez d'abord vos batailles, concentrez-vous sur les problèmes critiques qui se manifestent à vos utilisateurs afin que vous ne lanciez pas une volée de critiques contre la personne qui les conduit à rejeter tout ce que vous dites.
Le langage corporel et le tonus sont importants si vous leur parlez en personne, soyez clair avec ce que vous dites et assurez-vous de ne pas leur parler ou de ne pas rejeter leurs capacités techniques. Ils seront très probablement sur la défensive dès le départ, vous devez donc régler leurs inquiétudes au lieu de les confirmer. Vous devez être conscient de cette conversation sans être trop évident pour qu'ils pensent inconsciemment que vous êtes de leur côté, et j'espère qu'ils acceptent qu'ils doivent apporter les changements qui ont été portés à l'attention.
Si cela ne fonctionne pas, vous pouvez commencer à devenir un peu plus agressif. Si le produit peut être exécuté depuis une salle de conférence, montez-le sur le projecteur pendant la révision du code et montrez le bogue de première main, il vaut mieux qu'un gestionnaire soit là pour que la personne ne puisse pas reculer. Ce n'est pas pour leur faire honte, mais pour les forcer à accepter que le problème est réel pour l'utilisateur et qu'il doit être corrigé, au lieu d'un simple reproche que vous avez avec leur code.
Finalement, si vous n'allez nulle part, si vous en avez assez de traiter la personne comme un élève de maternelle et que la direction n'est pas du tout au courant du problème, cela ne reflète pas bien vos performances en tant que réviseur de code ou vous vous souciez du bien-être de votre entreprise et/ou produit, vous devez commencer à parler à votre patron de son comportement. Soyez aussi précis et impersonnel que possible - faites une analyse de rentabilité selon laquelle la productivité et la qualité souffrent.
Les révisions de code peuvent être toxiques, perdre du temps, entraîner des guerres de nerds qui sèchent la vie. Il suffit de regarder la divergence d'opinion sur des choses comme le code propre par rapport aux commentaires, les conventions de dénomination, les tests unitaires et d'intégration, les stratégies d'enregistrement, RESTfulness, etc., etc.
La seule façon de vous assurer d'éviter cela est de notez les règles pour passer un examen de code.
Ce n'est pas une personne qui échoue ou approuve l'enregistrement. Ils vérifient simplement que les règles ont été respectées.
Et parce qu'ils sont écrits à l'avance, lorsque vous écrivez votre code, vous pouvez suivre les règles et ne pas avoir à expliquer votre raisonnement ou avoir des arguments plus tard.
Si vous n'aimez pas les règles, organisez une réunion pour les modifier.
Je ne voudrais pas enrober vos commentaires, car ils peuvent être considérés comme condescendants.
À mon avis, la meilleure pratique est de toujours se concentrer sur le code et jamais sur l'auteur.
C'est un code avis, pas un développeur avis, donc:
- "Cette boucle peut ne jamais se terminer", et non "Votre boucle peut ne jamais se terminer"
- "Un scénario de test est nécessaire pour le scénario X", pas "Vous n'avez pas écrit le test pour couvrir ce scénario"
Il est également très important d'appliquer la même règle tout en parlant de l'examen avec d'autres:
- "Anne, que penses-tu de ce code?", Pas "Anne, que penses-tu du code de Jon?"
La révision du code n'est pas le moment de procéder à une évaluation des performances - elle doit être effectuée séparément.
Je suis surpris que cela n'ait été mentionné dans aucune réponse jusqu'à présent, et peut-être mon expérience avec les revues de code est inhabituelle, mais:
Pourquoi examinez-vous l'intégralité de la demande de fusion dans un seul message?
Mon expérience avec les revues de code se fait via GitLab; J'ai toujours imaginé que d'autres outils de révision de code fonctionneraient de la même manière.
Lorsque je donne un examen du code, je commente des lignes spécifiques et individuelles du diff. Il est extrêmement peu susceptible d'être reçu comme critique personnelle, car il s'agit d'un commentaire sur le code - et est en fait affiché sous forme de commentaire sur le code, affiché directement sous le code, il s'agit d'un commentaire.
Je peux également commenter l'intégralité de la demande de fusion, et je le fais souvent. Mais des points spécifiques peuvent être signalés sur des lignes spécifiques du diff. (De plus, lorsqu'un nouveau commit est ajouté de sorte que le diff change, les commentaires sur le "diff obsolète" sont masqués par défaut.)
Avec ce flux de travail, les revues de code deviennent beaucoup plus modulaires et moins cohésives. Une ligne d'une revue de code peut simplement dire,
Belle approche, enveloppant cela dans une fonction dédiée!
Ou cela pourrait dire,
Ce nom d'objet ne correspond pas vraiment au but de l'objet; peut-être pourrions-nous utiliser un nom comme "XYZ" à la place?
Ou s'il y a des problèmes majeurs avec une section, je pourrais écrire:
Je vois que ce code fonctionne (et je vois pourquoi cela fonctionne) mais il faut une étude ciblée pour le comprendre. Pourriez-vous le refactoriser en fonctions distinctes afin qu'il soit plus facile à maintenir à l'avenir?
(Exemple: la fonction ABC fait en fait trois choses ici: éblouir le foo, interdire le boz et frotter le zorf. Ce peuvent être toutes des fonctions séparées.)
Après avoir écrit tout ce qui précède, je peux faire un commentaire récapitulatif sur l'ensemble de la demande de fusion, quelque chose comme:
Il s'agit d'une excellente nouvelle fonctionnalité et elle sera vraiment utile une fois fusionnée. Pouvez-vous s'il vous plaît nettoyer le nom de la fonction et gérer la refactorisation mentionnée dans les commentaires individuels que j'ai faits, puis laissez-moi savoir de le revoir? :)
Même si la demande de fusion est un petit-déjeuner complet pour chien, les commentaires individuels peuvent chacun être simples. Il y en aura juste plus. Le résumé pourrait alors dire:
Je suis désolé, mais ce code n'est pas vraiment à la hauteur. Il existe un grand nombre de cas Edge (comme détaillé dans les commentaires individuels) qui seront traités de manière incorrecte et donneront une mauvaise expérience utilisateur, voire une corruption de données dans un cas. (Voir le commentaire sur la validation 438a95fb734.) Même certains cas d'utilisation normaux entraîneront des performances d'application extrêmement mauvaises (les détails sont notés dans les commentaires individuels sur le diff pour somefile.c).
Pour être prête pour la production, cette fonctionnalité nécessitera une réécriture complète en accordant plus d'attention aux hypothèses qu'il est sûr de faire à chaque point du flux. (Indice: aucune hypothèse n'est sûre à moins d'avoir été vérifiée.)
Je ferme la demande de fusion en attendant une réécriture complète.
Résumé: Passez en revue les aspects techniques du code sous forme de commentaires sur des lignes de code individuelles. Ensuite résumez ces commentaires dans un commentaire global sur la demande de fusion. Ne soyez pas personnel - traitez simplement les faits et à votre avis sur le code , pas sur le codeur. Et basez votre opinion sur des faits, une observation précise et une compréhension.
Je suis vraiment surpris que personne n'ait pris cela en compte, mais il y a quelque chose qui ne va pas avec l'examen de l'échantillon publié.
Il n'y a tout simplement aucune raison de s'adresser directement à Joe. Que Joe répare ses échecs ne vous regarde pas. C'est quelqu'un, c'est votre affaire. Votre souci est la qualité du code. Donc, au lieu d'écrire des demandes/commandes/demandes (que si j'étais Joe, je pourrais simplement refuser parce que vous n'êtes pas légitime pour cela), restez à votre rôle et écrivez une simple liste de tâches anonymes.
Essayer d'être juste en donnant de bons et de mauvais points est non seulement impossible, mais complètement hors de votre rôle.
Voici un exemple de reformulation avec un contenu tiré de votre avis:
- Avant de tirer des modifications dans la classe Library\ACME\ExtractOrderMail, nous devons résoudre quelques problèmes.
- Sauf si j'ai raté quelque chose, "TempFilesToDelete" ne devrait pas être statique.
- À l'avenir, nous pouvons appeler la fonction plus d'une fois par exécution, c'est pourquoi nous avons besoin (ce qui doit être fait ici).
- J'ai besoin de comprendre pourquoi "GetErrorMailBody" prend une exception comme paramètre. (et je suis à la limite ici, car maintenant, vous devriez déjà avoir un conclusion)
- SaveAndSend doit être renommé pour mieux s'adapter à son comportement, comme par exemple "SendErrorMail"
- Le code commenté doit être supprimé à des fins de lisibilité. Nous utilisons Subversion pour d'éventuelles annulations.
Si vous formulez la critique comme celle-ci, peu importe combien le lecteur vous déteste personnellement, tout ce qu'il peut voir ici, ce sont des notes sur les améliorations que quelqu'un doit poursuivre plus tard. Qui ? Quand ? Tout le monde s'en fout. Quoi ? Pourquoi ? QUE vous devriez dire.
Maintenant, vous aborderez la raison même pour laquelle les revues de code augmentent la tension en retirant le facteur humain de l'équation.
Le point essentiel de la révision du code est de trouver des problèmes. S'il y a any bug, la meilleure chose à faire est d'écrire un cas de test qui échoue.
Votre équipe (manager) devrait communiquer que la production de bugs fait partie du jeu, mais les trouver et les corriger vous fera économiser tout le monde travail.
Il pourrait être utile d'avoir des réunions régulières (en équipe ou en binôme) et de passer en revue quelques problèmes. Le programmeur d'origine n'a pas introduit de problèmes intentionnellement, et parfois il pourrait penser que c'était assez bon (et parfois il pourrait même l'être). Mais avoir cette deuxième paire d'yeux donne une vue complètement nouvelle, et il pourrait apprendre beaucoup en regardant les problèmes.
C'est vraiment une chose culturelle, et elle a besoin de beaucoup de confiance et de communication. Et le temps de travailler avec les résultats.
Je pense que la chose positive à faire serait de parvenir à un consensus sur les normes de codage avant de procéder à des examens. D'autres ont tendance à acheter davantage quelque chose lorsqu'ils ont leur mot à dire.
Pour quelque chose comme les conventions de dénomination, demandez aux autres si c'est important. La plupart des développeurs seront d'accord en particulier entre leurs pairs. Qui veut être la personne qui ne veut pas être d'accord avec quelque chose d'aussi répandu dans le monde de la programmation? Lorsque vous démarrez le processus en choisissant le code de quelqu'un et en signalant la faille, il devient très défensif. Lorsque des normes seront établies, il y aura un désaccord sur l'interprétation ou sur ce qui est considéré comme "assez bon", mais vous êtes mieux que vous ne l'êtes maintenant.
Une autre partie de ce processus consiste à déterminer comment les revues de code traiteront les objections. Cela ne peut pas devenir un débat sans fin. À un moment donné, quelqu'un doit prendre la décision. Peut-être qu'il peut y avoir un tiers pour être le juge ou le réviseur obtient tout le pouvoir. Les choses doivent être faites devrait être l'objectif.
La dernière partie de cela est de faire savoir à tout le monde que les révisions de code ne sont pas votre idée, elles vont rester, donc tout le monde devrait faire un effort pour en tirer le meilleur parti. Si tout le monde se sent impuissant, peut-être peut-il être autorisé à revoir votre code?
Avec un peu de chance, un résultat mesurable pour la gestion est de limiter les bugs, les plaintes des clients, les retards, etc. Sinon, quelqu'un vient d'entendre le mot à la mode "révision de code" et a pensé que s'il l'ajoutait à votre processus, des miracles se produiraient sans beaucoup de temps, d'énergie et les efforts consentis.
Cela peut être difficile, mais ne vous inquiétez pas de donner de bons commentaires s'il n'y a rien de bon à mesurer.
Cependant, à l'avenir, alors que vos développeurs commencent à améliorer leur code, c'est à ce moment-là que vous voudrez leur donner de bons commentaires. Vous voudrez souligner les améliorations du code, et vous voudrez également souligner les avantages pour l'équipe dans son ensemble. Lorsque vous commencez à voir une amélioration, ils le seront aussi, et les choses devraient lentement commencer à se produire.
Autre chose; il peut y avoir un air défensif parce qu'ils ont l'impression de ne pas avoir leur mot à dire. Pourquoi ne pas les laisser réviser le code de l'autre? Posez-leur des questions spécifiques et essayez de les impliquer. Ce ne devrait pas être vous contre eux; ce devrait être un effort d'équipe.
- Que changeriez-vous à propos de ce code si vous en aviez le temps?
- Comment amélioreriez-vous cette zone de la base de code?
Demandez-le maintenant et demandez-le dans six mois. Il y a une expérience d'apprentissage ici.
Le point principal - ne faites pas l'éloge en termes de code là où il n'est pas justifié, mais reconnaissez l'effort et reconnaissez définitivement l'amélioration. Essayez de faire des révisions un exercice d'équipe au lieu d'un exercice contradictoire.
Qualité sans tension
Vous avez demandé comment trouver des choses positives à dire sur le code, mais votre vraie question est de savoir comment éviter les "tensions au sein de [votre] équipe" tout en abordant les "graves problèmes de qualité".
La vieille astuce consistant à prendre en sandwich "mauvaises nouvelles et bonnes nouvelles" peut se retourner contre vous. Les développeurs sont susceptibles de le voir pour ce qu'il est: un artifice.
Problèmes de haut en bas de vos organisations
Vos patrons vous ont chargé d'assurer la qualité. Vous avez trouvé une liste de critères pour la qualité du code. Maintenant, vous voulez des idées de renforcement positif à fournir à votre équipe.
Pourquoi nous demander ce que vous devez faire pour rendre votre équipe heureuse? Avez-vous envisagé de demander à votre équipe?
Il semble que vous fassiez de votre mieux pour être agréable. Le problème n'est pas de savoir comment vous transmettez votre message. Le problème est que la communication a été à sens unique.
Construire une culture de la qualité
Une culture de la qualité doit être nourrie pour se développer de bas en haut.
Faites savoir à votre patron que vous craignez que la qualité ne s'améliore pas assez rapidement et que vous souhaitez essayer d'appliquer les conseils de The Harvard Business Review .
Rencontrez votre équipe. Modélisez les comportements que vous souhaitez voir dans votre équipe: humilité, respect et engagement à vous améliorer.
Dites quelque chose comme: "Comme vous le savez, [un collègue] et moi avons été chargés d’assurer la qualité du code, afin d’éviter le genre de problèmes de production que nous avons subis récemment. Personnellement, je ne pense pas avoir résolu ce problème. Je pense que ma plus grosse erreur n'a pas été de vous impliquer tous davantage au début. [collègue] et moi sommes toujours responsables à la direction pour la qualité du code, mais à l'avenir, nous sommes tous dans l'effort de qualité ensemble. "
Obtenez des idées de l'équipe sur la qualité du code. (Un tableau blanc aiderait.) Assurez-vous que vos exigences y parviennent à la fin. Proposez vos idées de manière respectueuse et posez des questions, le cas échéant. Soyez prêt à être surpris de ce que votre équipe estime important. Soyez flexible, sans compromettre les besoins de l'entreprise.
(Si vous avez un vieux code qui vous gêne, vous pouvez le trotter, encourageant tout le monde à être franc. À la fin, faites savoir aux gens que vous l'avez écrit. Modélisez la réaction mature que vous espérez lorsque d'autres reçoivent des critiques de construction. )
Revues de code collaboratif
Je n'ai pas travaillé dans un endroit comme vous le décrivez, où quelques programmeurs expérimentés examinent tout le code et apportent des corrections. Pas étonnant que les gens répondent comme si vous étiez un enseignant qui faisait des marques rouges sur leurs papiers.
Si vous pouvez vendre l'idée à la direction, commencez à faire revues de code par les pairs . Il est préférable de le faire en petits groupes, y compris vous ou l'autre développeur responsable. Assurez-vous que tout le monde est traité avec respect.
Un objectif important de l'examen par les pairs du code est de s'assurer que le code peut être compris par tous les membres de l'équipe. Considérez votre exemple de noms de fonction peu clairs: entendre un développeur plus jeune qu'il trouve le nom de la fonction déroutant peut être plus facile à accepter qu'une autre "correction" du développeur senior.
La qualité est un voyage
Une autre chose à faire est de supprimer toute notion selon laquelle une révision de code est une sorte de réussite/échec. Tout le monde devrait s'attendre à apporter quelques modifications après une révision du code. (Et votre travail consiste à vous assurer qu'ils se produisent.)
Mais si cela ne fonctionne pas ...
Supposons que vous progressiez dans la mise en place d'une culture de la qualité. Il se peut que vous n'ayez toujours pas tout le monde à bord. Si quelqu'un n'est toujours pas avec le programme de qualité, le problème est maintenant qu'il ne correspond pas à l'équipe, plutôt qu'il n'y a un problème entre vous deux. S'ils doivent être renvoyés de l'équipe, le reste de l'équipe comprendra mieux les raisons.
Désolé pour une autre longue réponse, mais je ne pense pas que les autres aient pleinement abordé l'élément humain de ce problème.
parfois même simplement demander pourquoi quelque chose a été mis en œuvre d'une manière spécifique. Quand je pense que c'est mauvais, je précise que je l'aurais développé d'une autre manière.
Le problème avec "Pourquoi l'avez-vous implémenté de cette façon?" c'est que vous mettez immédiatement le développeur sur la défensive. La question elle-même peut impliquer toutes sortes de choses selon le contexte: êtes-vous trop stupide pour penser à une meilleure solution? Est-ce le mieux que vous puissiez faire? Essayez-vous de ruiner ce projet? Vous souciez-vous même de la qualité de votre travail? etc. Demander "pourquoi" le code a été développé d'une certaine manière ne sera que conflictuel, et cela subvertit toute intention pédagogique que votre commentaire aurait pu avoir.
De même, "j'aurais fait ça différemment ..." est également conflictuel, car la pensée immédiate que le développeur aura sera " Eh bien, je l'ai fait de cette façon ... Vous avez un problème avec ça? "Et encore une fois, c'est plus conflictuel que nécessaire et détourne la discussion de l'amélioration du code.
Exemple:
Au lieu de demander "Pourquoi avez-vous choisi de ne pas utiliser la variable constante pour cette valeur?", Indiquez simplement "Cette valeur codée en dur doit être remplacée par la constante XYZ dans le fichier Constants.h". la question suggère que le développeur a activement choisi pas pour utiliser la constante déjà définie, mais il est tout à fait possible qu'ils ne savaient même pas qu'elle existait. Avec une base de code suffisamment grande, il y aura beaucoup de choses que chaque développeur ne sait pas. C'est simplement une bonne opportunité d'apprentissage pour ce développeur de se familiariser avec les constantes du projet.
Il y a une ligne fine pour marcher avec les revues de code: vous n'avez pas besoin de recouvrir tout ce que vous dites, vous n'avez pas besoin de prendre en sandwich les mauvaises nouvelles et les bonnes nouvelles, et vous n'avez pas besoin d'atténuer le coup. Cela pourrait être la culture dans laquelle je suis, mais mes collègues et moi ne nous complimentons jamais mutuellement dans les revues de code - les parties du code que nous développons qui sont sans défaut sont assez un compliment. Ce que vous devez faire, c'est identifier le défaut que vous voyez et peut-être en donner une raison (le pourquoi est moins utile quand c'est évident/simple).
Bien:
"Le nom de cette variable doit être modifié pour correspondre à notre norme de codage."
"Le 'b' dans ce nom de fonction doit être en majuscule pour être PascalCase."
"Le code de cette fonction n'est pas mis en retrait correctement."
"Ce code est un doublon de code trouvé dans
ABC::XYZ(), et devrait utiliser cette fonction à la place.""Vous devez utiliser try-with-resources pour que les choses soient correctement fermées dans cette fonction, même si des erreurs se produisent." [J'ai seulement ajouté un lien ici pour que les utilisateurs non Java sachent ce que signifie essayer avec des ressources]
"Cette fonction doit être refactorisée afin de répondre à nos normes de complexité à n chemins."
Mauvais:
"I pensez vous pourriez améliorer ce code en changeant le nom de la variable pour qu'elle corresponde à notre standard"
" Peut-être il serait préférable d'utiliser try-with-resource pour fermer correctement les choses dans cette fonction"
"Il pourrait être souhaitable de jeter un autre regard sur toutes les conditions de cette fonction. Sa complexité sur le chemin N est supérieure à la complexité maximale autorisée de notre standard."
"Pourquoi les retraits sont-ils ici de 2 espaces au lieu des 4 de notre standard?"
"Pourquoi avez-vous écrit une fonction qui rompt notre norme de complexité à n chemins?"
Dans les mauvaises déclarations, les parties en italique sont des choses que les gens utilisent couramment quand ils veulent adoucir le coup, mais tout ce qu'il fait vraiment dans une révision de code est de vous rendre incertain. Si vous, le réviseur, n'êtes pas certain de la façon d'améliorer le code, alors pourquoi quelqu'un devrait-il vous écouter?
Les `` bonnes '' déclarations sont directes, mais elles n'accusent pas le développeur, elles n'attaquent pas le développeur, elles ne sont pas conflictuelles et elles ne se demandent pas pourquoi le défaut existe. Ça existe; voici la solution. Ils ne sont certainement pas aussi conflictuels que cette dernière question "pourquoi".
Le problème que vous voyez est le suivant: les développeurs sont mécontents que leur code soit critiqué. Mais ce n'est pas le problème. Le problème est que leur code n'est pas bon (en supposant évidemment que vos critiques de code sont bonnes).
Si les développeurs n'aiment pas que leur code soit critiqué, la solution est simple: écrire un meilleur code. Vous dites que vous avez eu de sérieux problèmes avec la qualité du code; cela signifie qu'un meilleur code est nécessaire.
"Pourquoi la méthode devrait-elle avoir un nom raisonnable, je sais ce qu'elle fait?" est quelque chose que je trouve particulièrement inquiétant. Il sait ce que cela fait, ou du moins il le dit, mais je ne le sais pas. Toute méthode ne doit pas simplement avoir un nom sensible, elle doit avoir un nom qui indique immédiatement au lecteur le code qu'il fait. Vous voudrez peut-être aller sur le site Web d'Apple et rechercher une vidéo de la WWDC sur les changements de Swift 2 à Swift 3 - un grand nombre de changements effectués juste pour rendre ce tout plus lisible. Peut-être que ce type de vidéo pourrait convaincre vos développeurs que les développeurs qui sont beaucoup plus intelligents qu’eux trouvent les noms de méthodes intuitifs très, très importants.
Un autre élément inquiétant était votre collègue qui a déclaré "elle m'a dit elle-même qu'après qu'un rapport de bug a été déposé par un client, elle était au courant du bug, mais craignait que le développeur ne soit en colère contre elle pour l'avoir signalé". Il y a la possibilité qu'il y ait un malentendu, mais si un développeur devient fou si vous lui signalez un bogue, que est mauvais.
Je serais respectueusement en désaccord avec la méthode d'examen du code que vous avez décrite. Deux membres du personnel qui s'en vont dans une "pièce fermée" et qui émettent des critiques institutionnalisent le genre même de notion accusatoire selon laquelle de bonnes révisions de code devraient être éviter .
Faire de la révision du code une expérience positive dans la mesure du possible est essentiel à sa réussite. La première étape consiste à supprimer la notion accusatoire de révision. Faites-en un événement hebdomadaire ou bihebdomadaire groupe; assurez-vous que tout le monde sait qu'ils sont invités à participer. Commandez des pizzas ou des sandwichs ou autre chose. N'appelez même pas cela une "révision de code" si cela suscite des connotations négatives. Trouvez quelque chose à célébrer, à encourager, à partager - même si ce n'est rien de plus que de progresser dans le sprint ou l'itération en cours. Assignez à tour de rôle le leadership à l'examen.
Faire du processus un effort pour servir le produit et les gens. Si elles sont faites de manière constructive, positive, où les bonnes techniques ou les bons schémas sont partagés et encouragés tout comme les pauvres sont découragés - tout le monde en profite. Tout le monde est coaché en public. Si vous avez un programmeur à problèmes qui ne "comprend pas", ils doivent être adressés en privé et séparément - jamais devant le groupe plus large. C'est distinct de la révision du code.
Si vous avez du mal à trouver quelque chose de "bon" à soulever, cela me pose une question: si des progrès sont réalisés dans le projet et que les gens travaillent, ces progrès en soi sont quelque chose à célébrer. Si vous ne trouvez vraiment rien bon, cela implique que tout ce qui a été fait depuis le dernier examen est soit mauvais ou pas mieux que neutre . Est-ce vraiment le cas?
Quant aux détails, des normes communes sont essentielles. Donnez à chacun un intérêt dans ce qui se fait. Et permettent d'intégrer de nouvelles techniques améliorées dans votre base de code. L'omission de le faire garantit que les vieilles habitudes ne sont jamais excisées sous le couvert de "nous l'avons toujours fait de cette façon".
Le point dans tout cela est que les revues de code sont un peu malmenées parce qu'elles sont mal implémentées, utilisées comme des marteaux pour rabaisser les programmeurs moins expérimentés ou moins qualifiés, et cela n'est utile à personne. Les managers qui les utilisent de cette manière ne sont pas non plus des managers très efficaces. De bonnes revues de code dans lesquelles tout le monde est un participant servent tout le monde - le produit, les employés et l'entreprise.
Toutes mes excuses pour la durée de la publication, mais ayant fait partie d'un groupe où la révision du code a été largement ignorée, cela a conduit à un héritage de code incontrôlable et à un éventail restreint de développeurs capables même s'ils étaient autorisés à apporter des modifications à une base de code vieille de plusieurs années. C'était un chemin que je choisirais de ne pas parcourir à nouveau.
Le paradoxe d'un bon code est qu'il ne se démarque pas du tout, et semble être très simple et facile à écrire. J'aime vraiment l'exemple du joueur de billard de cette réponse . Dans les revues de code, cela facilite vraiment le survol, à moins qu'il ne s'agisse d'un refactoriseur de mauvais code.
Je tiens à le rechercher. Si je passe en revue le code et que j'ai parcouru un fichier si facile à lire qu'il semble trompeusement facile à écrire, je lance simplement un rapide "J'aime la façon dont les méthodes ici sont courtes et propres" ou tout ce qui est approprié .
En outre, vous devez donner l'exemple. Vous devez également insister pour que votre code soit révisé et modéliser la façon dont vous souhaitez que votre équipe se comporte lors de la réception de la correction. Plus important encore, vous devez sincèrement remercier les gens pour leurs commentaires. Cela fait plus de différence que tout commentaire unilatéral que vous pouvez donner.
Il semble que le vrai problème est que ce ne sont que deux personnes qui effectuent toutes les révisions de code, dont c'est seulement vous qui les prenez au sérieux, ce qui vous a conduit dans une situation malheureuse avec beaucoup de responsabilités et beaucoup de la pression des autres membres de l'équipe.
Une meilleure façon serait de répartir la responsabilité de la révision du code sur l'équipe et de faire participer tout le monde à cette tâche, par exemple en laissant les développeurs choisir qui réviser leur code. C'est quelque chose que votre outil de révision de code devrait prendre en charge.
J'ai vu cela de première main et je veux vous mettre en garde contre les intelligence émotionnelle réponses contestées - ils peuvent tuer des équipes entières. À moins que vous ne vouliez recruter, former et normaliser de nouveaux développeurs chaque année, il est essentiel de créer une relation positive avec vos pairs. Après tout, n'est-ce pas la raison de faire ces examens pour améliorer la qualité du code et favoriser une culture où la qualité du code est plus élevée en premier lieu? Je dirais que cela fait en effet partie de votre travail de fournir un renforcement positif comme moyen d'intégrer ce système de révision de code dans la culture d'équipe.
Quoi qu'il en soit, il semble que vous deviez revoir votre système de révision de code. À l'heure actuelle, à en juger par tout, tout dans votre processus d'examen est, ou peut être interprété comme, subjectif plutôt qu'objectif. Il est facile de se sentir blessé quand on a l'impression que quelqu'un choisit simplement votre code parce qu'il ne l'aime pas, plutôt que d'avoir une raison à citer quand quelque chose ne correspond pas aux directives. De cette façon, il est facile de suivre et de "célébrer" les améliorations positives de la qualité du code (par rapport à votre système de révision) de la manière qui convient à la culture de votre bureau.
Les responsables techniques doivent se réunir en dehors d'une session d'examen et mettre en place une liste de directives de codage/liste de contrôle pour l'examen du code et il doit être respecté et mentionné pendant l'examen. Il doit s'agir d'un document évolutif qui peut être mis à jour et affiné à mesure que le processus se développe. Ces réunions Tech Lead devraient également avoir lieu lorsque la discussion `` Façon dont nous avons toujours fait les choses '' ou `` Nouvelles façons améliorées de faire les choses '' devrait avoir lieu, sans que le développeur ne soit examiné comme si le désaccord était le résultat de leur code. Une fois que la ligne directrice initiale a été plus ou moins lissée, une autre façon de renforcer positivement les développeurs est de demander leur avis puis de prendre des mesures et faire évoluer le processus en équipe, cela fait des merveilles pour les mettre à niveau pour commencer à réviser le code pour les cartes à bord afin que vous ne soyez pas coincé à faire des révisions jusqu'à votre retraite, aussi.
Locaux...
Les programmeurs résolvent les problèmes. Nous sommes conditionnés pour commencer le débogage en cas de problème ou d'erreur.
Le code est un support au format contour. Le passage à un récit au format paragraphe pour les commentaires introduit une déconnexion qui doit être traduite. Inévitablement, quelque chose se perd ou est mal compris. Inévitablement, le réviseur ne parle pas dans le langage du programmeur.
Les messages d'erreur générés par ordinateur sont rarement remis en question et ne sont jamais considérés comme un affront personnel.
Les éléments de révision de code sont des messages d'erreur générés par l'homme. Ils sont destinés à détecter les cas Edge que les programmeurs et les outils automatisés manquent, ainsi que les effets secondaires inévitables sur d'autres programmes et données.
Conclusions ...
Ainsi, plus les éléments de révision de code peuvent être incorporés dans des outils automatisés, mieux ils seront reçus.
La mise en garde est que, pour rester incontestés, ces outils doivent être continuellement mis à jour, généralement quotidiennement ou hebdomadairement, pour être en conformité avec chaque changement des procédures, des normes et des pratiques. Lorsqu'un gestionnaire ou une équipe de développeurs décide d'apporter une modification, les outils doivent être modifiés pour appliquer cela. Une grande partie du travail du réviseur de code devient alors le maintien des règles dans les outils.
Exemple de commentaires de révision de code ...
Une réécriture de l'exemple donné incorporant ces techniques:
Matière:
- Bibliothèque\ACME\Classe ExtractOrderMail.
Question principale ...
- TempFilesToDelete est statique
- Les appels suivants à GetMails lèvent une exception car des fichiers y sont ajoutés mais ne sont jamais supprimés après la suppression. Bien qu'il n'y ait qu'un seul appel maintenant, les performances pourraient être améliorées à l'avenir avec un certain parallélisme.
- TempFilesToDelete en tant que variable d'instance permettrait à plusieurs objets d'être utilisés en parallèle.
- Problèmes secondaires ...
- GetErrorMailBody a un paramètre d'exception
- Puisqu'il ne lève pas lui-même une exception et la transmet simplement à ToString, est-ce nécessaire?
- Nom SaveAndSend
- L'e-mail peut être utilisé ou non pour signaler cela à l'avenir et ce code contient la logique générale pour stocker une copie persistante et signaler toute erreur. Un nom plus générique permettrait de telles modifications anticipées sans modification des méthodes dépendantes. Une possibilité est StoreAndReport.
- Commenter l'ancien code
- Laisser une ligne commentée et marquée OBSOLETE peut être très utile dans le débogage, mais un "mur de commentaires" peut également masquer les erreurs dans le code adjacent. Nous l'avons toujours dans Subversion. Peut-être juste un commentaire référençant exactement où dans Subversion?
Si vous n'avez rien de gentil à dire sur le code existant (ce qui semble compréhensible), essayez d'impliquer le développeur dans son amélioration.
Dans un patch pour un changement fonctionnel ou un bug, il n'est pas utile d'avoir d'autres changements (renommage, refactoring, peu importe), regroupés dans le même patch. Il devrait apporter la modification qui corrige le bogue ou ajoute la fonctionnalité, rien d'autre.
Lorsque le changement de nom, le refactoring et d'autres changements sont indiqués, faites-les dans un patch séparé, avant ou après.
C'est assez moche, mais je suppose que c'est cohérent avec tous nos autres codes méchants. Nettoyons cela plus tard (dans un patch avec, idéalement, aucun changement fonctionnel).
Cela aide également si vous vous joignez à la refactorisation et laissez eux réviser votre code. Cela vous donne une chance de dire pourquoi vous pensez que quelque chose est bon plutôt que mauvais, et aussi de montrer un exemple de bonne critique constructive.
Si vous devez ajouter des tests unitaires à une nouvelle fonctionnalité, très bien, ils vont dans le patch principal. Mais si vous corrigez un bogue, les tests devraient aller dans un correctif antérieur et ne pas réussir afin que vous puissiez démontrer que le correctif a réellement corrigé le bogue.
Idéalement, le plan (pour savoir comment tester un correctif, ou ce qu'il faut refactoriser et quand) devrait être discuté avant que le travail soit terminé, afin qu'ils n'aient pas investi beaucoup d'efforts dans quelque chose avant de découvrir que vous avez un problème avec cela.
Si vous trouvez que le code ne gère pas les entrées que vous pensez qu'il devrait, il peut également y avoir un décalage dans ce que le développeur considère comme une entrée raisonnable. Acceptez cela à l'avance aussi, si possible. Au moins, discutez de ce à quoi il devrait pouvoir faire face et de la façon dont il peut être autorisé à échouer.
Je pense que c'est une erreur de supposer qu'il existe une solution technique ou facile à: "mes collègues sont bouleversés lorsque je juge leur travail par rapport à mes normes et ont un certain pouvoir pour le faire respecter".
N'oubliez pas que les révisions de code ne sont pas seulement une discussion de ce qui est bon ou mauvais. Ils sont implicitement un "qui est le bâton de mesure que nous utilisons", un "qui prend la décision" et, par conséquent - insidieusement - un rang.
Si vous n'abordez pas ces points, faire des révisions de code d'une manière qui n'a pas les problèmes que vous rencontrez sera difficile. Il y a de bons conseils ici sur la façon de le faire, mais vous vous êtes fixé une tâche difficile.
Si vous avez raison, sans aucune marge de manœuvre, le signaler est une attaque: quelqu'un a foiré. Sinon: votre autre MBA qui ne l'obtient pas. De toute façon, tu vas être le méchant.
Cependant, si ce que la critique cherche et pourquoi, est clair et convenu, vous avez une bonne chance de ne pas être le méchant. Vous n'êtes pas le portier, juste un correcteur d'épreuves. Obtenir cet accord est un problème difficile à résoudre [1]. Je voudrais vous donner des conseils, mais je ne l'ai pas encore compris moi-même ...
[1] Ce n'est pas résolu simplement parce que les gens ont dit "ok", ou ont cessé de se battre à ce sujet. Personne ne veut être le type à dire que X n'est tout simplement pas pratique pour notre {intelligence, expérience, main-d'oeuvre, délais, etc.} mais cela ne signifie pas quand il s'agit en fait d'une instance spécifique de faire X ...