Quelle est la meilleure façon de commenter une révision de code?

Mon équipe vient de commencer à utiliser creuset / fisheye pour lancer des révisions de code chaque fois que l'un de nous vérifie quelque chose. Nous ne sommes que 3, et nous sommes chacun encouragés à réviser le code et à laisser des commentaires où nous le jugeons approprié.

Ma question est la suivante: comment laisser au mieux un commentaire sur une ligne de code avec laquelle je vois un problème? Je veux faire passer mon message sans paraître abrasif.

Je ne veux pas avoir l'air d'être sur un cheval élevé et dire " Je l'ai fait de cette façon ... et je ne veux pas non plus avoir l'air de faire autorité et dire quelque chose comme " Cela devrait être fait de cette façon ... " mais je dois encore faire comprendre que ce qu'ils font n'est pas très bon.

Pour clarifier: Ceci est une très bonne ressource pour ce que je devrais chercher à commenter: une revue de code est-elle subjective ou objective (quantifiable)? , mais je cherche comment commenter cela.

Eh bien, j'ai tendance à faire des commentaires dans plusieurs domaines généraux et chaque type peut être traité différemment.

Modifications requises. Ce sont les types de changements où je souligne que le code ne répond pas aux exigences fonctionnelles ou ne fonctionne pas et doit être corrigé avant d'être poussé en production. J'ai tendance à être très simple dans ces commentaires. Les exigences disent ..., cela ne fait pas ça. Ou cela échouera si la valeur envoyée est nulle (surtout lorsque vous savez que ce cas se produira en fonction des données qui seront envoyées).

Ensuite, il y a les commentaires «cela fonctionne, mais voici une meilleure façon d'accomplir cela». Vous devez être plus doux dans ces domaines et faire plus d'argument de vente. Je pourrais dire que je le ferais à la place, car il est susceptible d'être plus performant (je passe généralement en revue le code SQL où les performances sont très importantes). Je pourrais ajouter quelques détails sur la raison pour laquelle c'est un meilleur choix, tout comme je le ferais pour répondre à une question sur Stack Overflow. Je pourrais souligner qu'il n'est pas nécessaire de changer cela pour ce code particulier, mais de considérer le changement dans le codage futur. Fondamentalement, avec ces types de commentaires, j'éduque les personnes ayant moins d'expérience sur ce qui pourrait mieux fonctionner.

Ensuite, il y a les commentaires "ça marche mais on fait les choses comme ça". Ces modifications seront probablement également nécessaires. Cela inclurait des commentaires sur les normes de l'entreprise ou l'architecture que nous attendons d'eux. Je voudrais faire référence à la norme ou au document d'architecture et leur dire de se conformer à la norme. Le commentaire serait simple mais neutre, il manque ainsi et ainsi ou les noms de variables ne sont pas conformes à notre standard de nommage ou à des choses similaires. Par exemple, notre architecture pour les packages SSIS nécessite que le package utilise notre base de données de métadonnées pour stocker des informations particulières sur le package et nécessite une journalisation particulière. Le package fonctionnerait sans ces éléments, mais ils sont nécessaires pour des raisons d'entreprise (nous devons par exemple signaler le taux de réussite des importations ou analyser les types d'erreurs que nous recevons.)

La seule chose que vous ne voulez pas faire dans les commentaires de révision de code est d'attaquer personnellement quelqu'un. Cela peut aussi être utile si vous trouvez quelque chose qu'ils ont bien fait et que c'est bon. Parfois, j'apprends quelque chose de nouveau à partir d'une revue de code et si je le fais, je le dis à la personne.

Si le code suit vos normes de codage, mais vous le feriez d'une manière différente, vous devez vous demander si ce qu'ils ont fait est mal.

Si ce n'est pas ... ce n'est tout simplement pas la façon dont vous l'auriez fait et vous ne pouvez pas le laisser, essayez simplement de demander 'Pourquoi l'avez-vous fait de cette façon plutôt que de cette façon?' Ensuite, vous leur faites comprendre pourquoi ils l'ont fait comme ils l'ont fait sans dire `` Je l'aurais fait de cette façon et vous devriez aussi ... ''

Vous pourriez également apprendre quelque chose au cours du processus.

Je veux faire passer mon message sans paraître abrasif.

Ne confondez pas la concision avec le fait d'être abrasif. Quand quelque chose pose problème, documentez-le de manière à ce que celui qui va le résoudre puisse le comprendre. Restez fidèle aux faits et n'écrivez pas de dissertation. En être témoin:

• Cela provoquera un dysfonctionnement du frobnitz lorsque le fooble se trouve à moins de 5 grimbles du facteur snorgatz.

• La convention établie pour ce faire est d'appeler fazzatz () avec un Squidge fraîchement initialisé. Faites-en une méthode pour que cela se produise toujours de la même manière et ne soit pas dupliqué.

  Je ne veux pas non plus avoir l'air d'être en train de faire autorité et de dire quelque chose comme "Cela devrait être fait de cette façon ..." mais j'ai encore besoin de faire comprendre que ce qu'ils font n'est pas très bon .

Le but de l'examen du code est de mettre une seconde paire d'yeux, généralement plus expérimentée, pour détecter les problèmes. Si vous êtes en mesure de porter un jugement sur le travail des autres et qu'il y a une raison valable de dire que quelque chose n'est pas bon, vous négligeriez votre responsabilité de réviseur si vous ne le faisiez pas.

Il y aura des désaccords, et ce sont des occasions pour le réviseur et le révisé de défendre leurs positions. Si vous êtes autrement des pairs et que vous atteignez une impasse, trouvez quelqu'un de plus âgé pour rompre le lien.

Cela dépend du type de problème qui a été constaté

• avis de copywrite manquant - un problème commun et ennuyeux juste un bref commentaire indiquant le problème et passer à autre chose
• les endroits où je pourrais le faire différemment - ont généralement tendance à poser des questions ici plutôt qu'à faire des déclarations, parfois les réponses justifieront la solution originale d'autres fois pas et ensuite je pourrai y répondre de manière plus explicite
• les endroits où il y a un défaut clair, par exemple un remplacement égal qui peut empiler le flux - atteindre le stylo rouge - le marquer comme un défaut et être très explicite quant à la raison pour laquelle il est cassé - vérifiez également d'autres zones similaires pour vérifier qu'il n'y a pas eu de problème systématique.

Selon mon expérience:

1. Ayez toujours l'auteur du code avec vous lors de la révision de son code. De préférence, le code est projeté sur le tableau blanc et vous pouvez clairement voir le code très bien.

2. Ayez une conversation amicale. Appréciez la bonne partie du codage. Dites-lui que "c'est le meilleur que j'ai vu" si vous voyez de bonnes parties dans le code.

3. Demandez-lui de revoir votre code et d'accepter et d'accepter les points valides et de le corriger. Respectez ses commentaires dans votre code et il respectera automatiquement vos commentaires de révision de code.
4. Traitez au niveau du développeur, sauf si cela est très important ou si plus de temps est nécessaire pour corriger les problèmes de révision du code. N'escaladez pas les gestionnaires pour des problèmes simples si la condition manque.
5. Regardez avec la perspective de «Apprendre à partir d'un autre code» au lieu de pointer des erreurs dans le code.
6. Pendant les séances de révision de code, citez les erreurs passées que vous avez commises et comment les révisions de code vous ont aidé et évité les gros problèmes de production, car une autre paire d'yeux vous a aidé.
7. Être humble. Plus d'appréciation et moins de commentaires pour lui :) Vous apprendrez beaucoup lors de la révision du code et il acceptera aussi volontiers vos commentaires.