Comment puis-je traiter avec un membre de l'équipe qui n'aime pas faire des commentaires dans le code?
Un des membres de mon équipe évite systématiquement de faire des commentaires dans son code.
Son code n'est pas auto-documenté, et d'autres programmeurs ont du mal à comprendre son code.
Je lui ai demandé à plusieurs reprises de commenter son code, mais il donne juste des excuses ou affirme qu'il le fera plus tard. Il craint que l'ajout de commentaires prenne trop de temps et retarde les projets.
Quel argument puis-je lui présenter pour le convaincre de bien documenter son code?
Sur cette note, ai-je tort de me concentrer sur les commentaires du code ou cela indique-t-il un problème plus important qui devrait être résolu?
Les commentaires seuls ne permettent pas d'obtenir un meilleur code, et le simple fait de demander "plus de commentaires" ne vous donnera probablement pas plus que /* increment i by 1 */ commentaires de style.
Alors demandez-vous pourquoi vous voulez ces commentaires. "C'est la meilleure pratique" ne compte comme argument que si vous comprenez pourquoi.
Maintenant, la raison la plus frappante pour utiliser des commentaires est pour que le code soit plus facile à comprendre, et lorsque les gens se plaignent de l'absence de commentaires, ce sont soit des perroquets désemparés, soit ils ont du mal à comprendre le code avec lequel ils travaillent.
Alors ne vous plaignez pas des commentaires manquants: plaignez-vous du code illisible. Ou mieux encore, ne vous plaignez pas, continuez à poser des questions sur le code. Pour tout ce que vous ne comprenez pas, demandez à la personne qui l'a écrit. Vous devriez le faire de toute façon; avec un code illisible, vous n'aurez qu'à poser plus de questions. Et si vous revenez à un morceau de code plus tard, et que vous n'êtes pas sûr de vous souvenir correctement de ce qu'il fait, posez à nouveau la même question.
Si les commentaires peuvent le corriger et que votre collègue a un cerveau qui fonctionne, il/elle se rendra compte à un moment donné qu'il est beaucoup plus facile de commenter le code que de vous poser des questions stupides tout le temps. Et si vous ne pouvez pas poser de questions, alors peut-être que ce code est déjà parfaitement lisible, et c'est vous qui êtes en faute - après tout, tout le code n'a pas besoin de commentaires.
Sur le plan des compétences humaines, évitez de paraître condescendant ou accusateur à tout prix; soyez sérieux et honnête au sujet de vos questions.
J'ai rencontré beaucoup de développeurs qui ont eu du mal à écrire du code auto-documenté ou des commentaires utiles. Ces types de personnes manquent souvent de suffisamment d'autodiscipline ou d'expérience pour bien faire les choses.
Ce qui ne fonctionne jamais, c'est de "leur dire d'ajouter plus de commentaires". Cela n'augmentera ni leur autodiscipline ni leur expérience. À mon humble avis, la seule chose qui pourrait fonctionner est de faire des révisions de code fréquentes et des sessions de refactoring. Lorsqu'un développeur a terminé une tâche, permettez-lui d'expliquer toutes les parties du code que vous ne comprenez pas. Refacturez immédiatement ou documentez le code de manière à ce que vous compreniez tous les deux 6 mois plus tard.
Faites-le sur une période de quelques mois, au moins deux fois par semaine. Si vous avez la chance, les autres développeurs apprendront à travers ces sessions afin que vous puissiez réduire la fréquence de révision.
Je suis surpris que personne n'ait encore mentionné de revues de code. Faites des revues de code! Quand il a un chèque de mauvaise qualité, ne dites pas simplement "ajouter des commentaires". Posez constamment des questions et demandez-lui de vous expliquer ce que fait son code et pourquoi. Prendre des notes. Ensuite, à la fin de la révision du code, donnez-lui une copie des notes et dites-lui de rendre vos questions assez évidentes. Soit par plus de commentaires ou juste en refactorisant son code pour le rendre de meilleure qualité (de préférence ce dernier quand c'est possible)
Cela dépend du code produit par votre collaborateur. Si vous lisez le livre Clean Code d'oncle Bob, vous constaterez qu'il préfère en fait ne pas ajouter des commentaires au code. Si le code lui-même est aussi lisible qu'il devrait l'être, alors il n'y a pratiquement pas besoin de commentaires.
Si ce n'est pas le cas, ou si vous avez besoin de commentaires en raison d'une politique non négociable, alors la question principale est de savoir si c'est seulement vous qui le veut/elle d'écrire des commentaires, ou si c'est toute l'équipe ou le chef d'équipe/projet. Si c'est juste vous, alors vous devriez parler à vos autres collègues pour savoir pourquoi ce n'est peut-être pas si grave du tout.
Si le chef de projet n'a pas les commentaires, vous pouvez également les exiger dans le cadre de l'exhaustivité , c'est-à-dire si le code soumis manque de commentaires, le travail n'est pas encore terminé. Il ne peut pas continuer à faire d'autres travaux jusqu'à ce que son travail actuel soit terminé et pour cela des commentaires sont requis. Cependant, gardez à l'esprit que ce type de forçage entraînera très probablement des commentaires horribles (attendez-vous à des tas de commentaires de répétition de code).
La seule façon possible, à mon humble avis, est de discuter des bénéfices réels que vous et tous les autres tirez des commentaires. Si il/elle ne le comprend pas par simple discussion, il y a toujours la difficulté: au lieu de les laisser écrire du nouveau code, faites-les travailler sur du code existant. Si possible, vous devriez leur trouver deux zones de travail différentes - une avec des commentaires utiles appropriés et une autre qui manque de commentaires. Devoir lire le code non lisible non commenté de quelqu'un d'autre est une révélation en ce qui concerne votre propre travail.
Nous y sommes tous allés une fois et nous étions en colère contre l'auteur original d'une source pour un travail aussi bâclé. C'est la réflexion supplémentaire que chacun de nous est aussi un auteur qui vous fait réaliser que vous devez vous soucier de la lisibilité - donc, n'oubliez pas de discuter des résultats avec votre collègue par la suite afin de promouvoir cette réflexion.
Si vous avez un employé qui ne peut pas suivre les instructions, réprimandez-le et assurez-vous qu'il est clair que cela n'aidera pas sa carrière à progresser. La cohérence dans le style de codage est essentielle pour une équipe, et si tout le monde écrit des commentaires et que celui-ci ne l'est pas, cela nuira au style de codage.
Cela dit, vous pouvez probablement l'aider. D'après mon expérience, quand quelqu'un proteste contre ce commentaire prend trop de temps il y a une barrière psychologique telle que…
- Il est conscient de ses choix de code/conception et ne veut pas les exposer en prose. (Les révisions de code peuvent être utiles pour renforcer la confiance en soi d'une personne autant que pour la détruire.)
- Il travaille de façon très linéaire et ne pense pas beaucoup à l'avenir. Commenter est douloureux car il l'oblige à décharger le code immédiat qu'il était sur le point d'écrire de sa mémoire de travail afin de composer son intention d'une manière différente. (Si cela est vrai, les commentaires deviennent très importants pour la qualité de son code.)
- Historiquement, les gens ne comprennent pas ses commentaires.
Il est important pour un programmeur de réaliser que les commentaires sont comme des tests: ils ne sont pas juste pour une utilisation future - ils sont pour le programmeur lui-même. Ils l'obligent à penser différemment son approche.
Rien de tout cela ne remplace un CI, des tests ou des revues de code. Ce n'est qu'une des nombreuses parties critiques du codage qui, en soi, n'écrit pas de code.
Obtenez un logiciel de révision de code et utilisez-le bien.
Nous utilisons Kiln et nous l'adorons. Nous avons une politique selon laquelle chaque ensemble de modifications doit être examiné (bien que nous permettions aux développeurs d'augmenter/d'approuver les avis pour eux-mêmes sur les balises et les fusions sans conflit (bien que la plupart d'entre nous utilisent rebaseif); de cette façon, nous pouvons rapidement repérer les ensembles de modifications sans avis).
Un code qui n'est pas clair est la raison pour laquelle une révision de code est rejetée. Peu importe que le correctif soit un commentaire ou un code plus clair, mais le réviseur doit être capable de le comprendre. Certains développeurs préfèrent réécrire le code, mais d'autres (moi y compris) trouvent souvent plus facile d'exprimer l'intention dans les commentaires (le code peut facilement montrer ce qu'il fait, mais il est plus difficile de montrer ce qu'il devrait faire).
S'il y a un doute sur la clarté du code, le réviseur gagne toujours. Bien sûr, l'auteur le comprend, car il l'a écrit. Cela doit être clair pour une autre personne.
En utilisant un logiciel comme Kiln, aucun ensemble de modifications n'est ignoré. Tout le monde dans mon équipe de développement préfère de beaucoup cette façon. Le logiciel de révision de code a eu un impact énorme sur la qualité de notre code et sur la qualité des applications :-)
Il est facile pour les développeurs de se mettre sur la défensive avec les critiques rejetées lors de la première introduction du logiciel, mais d'après mon expérience, il ne leur faut pas longtemps pour réaliser que les choses vont mieux de cette façon et l'embrasser :-)
Edit: A noter également, nous essayons de ne pas demander aux développeurs d'expliquer le code crypté verbalement ou dans les commentaires dans la revue. Si quelque chose n'est pas clair, le meilleur endroit pour l'expliquer est dans le code (dans les commentaires ou en refactorisant), puis ajoutez les nouveaux changesets à la même revue.
Intéressant, que lisibilité appliqué au langage naturel est mesuré par la vitesse de lecture et de compréhension. Je suppose qu'une règle simple peut en effet être adoptée, si un commentaire de code particulier n'améliore pas cette propriété, il peut être évité.
Pourquoi des commentaires?
Bien que le commentaire de code soit une forme de documentation intégrée, il existe plusieurs façons dans les langages de programmation haut de gamme pour éviter une programmation "surdocumentée" superflue (de code significatif) en utilisant des éléments du langage lui-même. C'est aussi une mauvaise idée de transformer le code en listes à partir du manuel de programmation, où les déclarations individuelles sont littéralement expliquées de façon presque tautologique (faites attention à l'exemple "/ * incrément i de 1 * /" dans les réponses déjà fournies), rendant ces commentaires pertinents uniquement aux programmeurs inexpérimentés avec la langue.
Néanmoins, c'est l'intention d'essayer de commenter le code "sous-documenté" (mais vide de sens) qui est vraiment "la source de tout mal". L'existence même d'un code "sous-documenté" est un mauvais signal - que ce soit un désordre non structuré, ou un hack farfelu d'un but mystique perdu. De toute évidence, la valeur d'un tel code est au moins discutable. Malheureusement, il existe toujours des exemples, quand il est en effet préférable d'introduire un commentaire dans une section de lignes de code formatées (visuellement groupées) plutôt que de l'envelopper dans un nouveau sous-programme (gardez à l'esprit la "cohérence stupide" qui "est le hobgobelin des petits esprits") .
Lisibilité du code! = Commentaires sur le code
Le code lisible ne nécessite pas d'annotations par les commentaires. À chaque endroit particulier du code, il y a toujours un contexte de tâche que ce code particulier est censé accomplir. Si le but est manquant et/ou le code fait quelque chose de mystérieux = évitez-le à tout prix. Ne laissez pas des hacks étranges remplir votre code - c'est le résultat direct de la combinaison de technologies de buggy avec un manque de temps/d'intérêt pour comprendre les fondements. Évitez le code mystique dans votre projet!
D'autre part, Programme lisible = code + documentation peut contenir plusieurs sections légitimes de commentaires, par exemple pour faciliter la génération de la documentation "commentaires à l'API".
Suivez les normes de style de code
Assez drôle, la question n'est pas de savoir pourquoi commenter le code, c'est du travail d'équipe - comment produire du code dans un style hautement synchronisé (que tout le monde peut lire/comprendre). Suivez-vous des normes de style de code dans votre entreprise? Son objectif principal est d'éviter d'écrire du code qui nécessite une refactorisation, est trop "personnel" et "subjectivement" ambigu. Donc je suppose que si l'on voit la nécessité d'utiliser le style de code, il y a tout un tas d'outils pour l'implémenter correctement - en commençant par éduquer les gens et en terminant par l'automatisation pour le contrôle de la qualité du code (nombreux lints, etc.) et (révision contrôle intégré) des systèmes de révision de code.
Devenez un évangéliste de la lisibilité du code
Si vous acceptez que le code soit lu plus souvent qu'il n'est écrit. Si une expression claire des idées et de la pensée est clairement importante pour vous, quelle que soit la langue utilisée pour communiquer (mathématiques, code machine ou vieil anglais) .. Si votre mission est d'éradiquer une façon ennuyeuse et laide de penser alternativement .. (désolé , le dernier vient d'un autre "manifeste") .. poser des questions, lancer des discussions, commencer à diffuser des livres qui suscitent la réflexion sur le nettoyage de code (probablement non seulement quelque chose de similaire aux modèles de conception de Beck, mais plus comme déjà mentionné par RC Martin ) qui abordent l'ambiguïté dans la programmation. Va plus loin un passage de balle-point des idées principales (cité du livre d'O'Reilly sur la lisibilité)
- Simplifiez la dénomination, les commentaires et la mise en forme avec des conseils qui s'appliquent à chaque ligne de code
- Affinez les boucles, la logique et les variables de votre programme pour réduire la complexité et la confusion
- Problèmes d'attaque au niveau de la fonction, tels que la réorganisation de blocs de code pour effectuer une tâche à la fois
- Écrivez un code de test efficace, complet et concis, ainsi que lisible
En supprimant les "commentaires", il en reste encore beaucoup (je suppose écrire du code qui n'a pas besoin de commentaires est un excellent exercice!). Nommer des identifiants sémantiquement significatifs est un bon début. Ensuite, structurer votre code en regroupant les opérations connectées logiquement en fonctions et classes. Etc. Un meilleur programmeur est un meilleur écrivain (bien sûr, en supposant d'autres compétences techniques données).
ai-je tort de me concentrer sur les commentaires du code ou cela indique-t-il un problème plus important qui devrait être résolu?
Quelque peu. Un bon code n'a pas besoin de commentaires. Cependant, comme vous l'avez dit, son code n'est pas auto-documenté. Je ne me concentrerais donc pas sur les commentaires. Vous devez vous concentrer sur l'amélioration des compétences et du savoir-faire de vos développeurs.
Alors comment faire ça? Les suggestions de Doc Brown sur les sessions de révision/refactoring sont une bonne idée. Je trouve la programmation par paires encore plus efficace, mais elle peut également être considérablement plus difficile à mettre en œuvre.
Tout d'abord, je vous suggère de reconsidérer votre approche concernant les commentaires.
S'il s'agit de commentaires de documentation au niveau de l'API (exposés plus tard au public), ce développeur ne fait tout simplement pas son travail. Mais pour tous les autres commentaires, soyez prudent.
Dans la plupart des cas où je les rencontre, les commentaires sont mauvais. Je recommanderais de lire le chapitre des commentaires de code de "Clean code" de Robert Martin pour bien comprendre pourquoi.
Les commentaires blessent votre code de plusieurs manières:
1) Ils sont difficiles à entretenir. Vous devrez faire un travail supplémentaire lors de la refactorisation; si vous modifiez la logique décrite dans le commentaire, vous devez également modifier le commentaire.
2) Ils mentent souvent. Vous ne pouvez pas faire confiance aux commentaires et devez plutôt lire le code. Ce qui soulève la question: pourquoi auriez-vous besoin des commentaires?
// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
//the calculation of the hash
int result = a*b;
}
(Le hachage n'est pas la somme mais le produit.)
3) Les commentaires encombrent le code et ajoutent très rarement une valeur.
Ma solution: au lieu d'ajouter plus de commentaires, essayez de vous en débarrasser!
Compte tenu des opinions souvent extrêmes sur les commentaires, j'hésite à peser. Cela étant dit ...
Quels sont les arguments que je peux présenter si vous voulez écrire du code (illisible) qu'il devrait être correctement documenté?
Comprendre comment écrire du code maintenable et lisible prend du temps, de la pratique et de l'expérience. Les programmeurs inexpérimentés (et malheureusement de nombreux expérimentés) souffrent souvent de l'effet Ikea ( PDF ). C'est parce qu'ils l'ont construit et le connaissent intimement, et ils sont sûrs que le code est non seulement génial, mais aussi lisible.
Si la personne est un grand programmeur, peu ou pas de documentation n'est requise. Cependant, la plupart des programmeurs ne sont pas géniaux et une grande partie de leur code souffrira dans le département de "lisibilité". Demander au programmeur médiocre ou en développement "d'expliquer son code" est utile en ce qu'il les oblige à voir leur code d'un œil plus critique.
Est-ce à dire "documenter" leur code? Pas nécessairement. Par exemple, j'avais un programmeur similaire avec ce problème dans le passé. Je l'ai forcé à documenter. Malheureusement, sa documentation était aussi indéchiffrable que son code, et n'ajoutait rien. Rétrospectivement, les revues de code auraient été plus utiles.
Vous (ou un délégué) devriez vous asseoir avec ce programmeur et récupérer une partie de son ancien code. Pas les nouveaux trucs qu'il connaît en travaillant dessus. Vous devriez lui demander de vous guider à travers son code avec une interaction minimale. Il peut également s'agir d'une session de "documentation" distincte, où il doit expliquer par écrit son code. Ensuite, il devrait obtenir des commentaires sur de meilleures approches.
En passant ... une certaine documentation est parfois nécessaire quelle que soit la qualité de la "lisibilité" du code. Les API devraient avoir de la documentation, les opérations extrêmement techniques et complexes devraient avoir de la documentation pour aider le programmeur à comprendre les processus impliqués (souvent en dehors du domaine de connaissances des programmeurs), et certaines choses comme les expressions rationnelles complexes devraient vraiment documenter ce que vous comparez.
Il s'agit en grande partie d'une extension de la réponse de tdammers, mais effectuez des révisions de code à intervalles réguliers.
Le faire (et d'autres développeurs) s'asseoir, parcourir leur code et se défendre plus ou moins devant leurs supérieurs et leurs pairs fera de tout le monde de meilleurs codeurs et ajoutera une valeur réelle sur une période de temps relativement courte. À court terme, cela ne donnera au développeur en question aucune excuse pour, au moment de la révision, commenter correctement son code.
EDIT: Je ne sais pas pourquoi quelqu'un rejetterait ma suggestion - j'ai peut-être pris pour acquis que les avantages de la révision du code seraient de notoriété publique ... veuillez consulter ce fil pour une analyse communautaire de la pratique:
Si un membre de l'équipe a du mal à comprendre le code d'un autre membre de l'équipe (pour une raison quelconque); ensuite, ce membre de l'équipe devrait être en mesure de savoir qui a écrit le code d'origine (tout système de contrôle des révisions sain d'esprit) et devrait être encouragé à demander à l'auteur du code de l'expliquer directement (par exemple, se diriger vers son bureau, s'asseoir et en discuter).
Dans ce cas, si le manque de commentaires est un problème, la personne qui ne commente pas correctement son code passera une grande partie de son temps à expliquer ce qu'elle a fait; et (s'ils sont intelligents) commenceront à ajouter des commentaires pour éviter de passer du temps sur toutes ces explications.
Notez qu'encourager les membres de l'équipe à se demander mutuellement des explications est utile pour d'autres raisons. Par exemple, un membre de l'équipe est peut-être moins expérimenté et peut apprendre des choses des membres de l'équipe plus expérimentés.
Surtout, en encourageant les membres de l'équipe à se demander mutuellement des explications, vous créez un système d'auto-équilibrage; où différents membres de l'équipe "s'auto-ajustent" les uns aux autres.
J'adore les réponses de révision de code, mais peut-être que mon processus aidera un peu aussi.
J'adore les commentaires, mais je ne les ajoute presque jamais dans le code lors de la première passe. C'est peut-être juste mon style mais je vais frapper la même section de code 3 à 5 fois pendant le développement (refactoring, écriture de tests, etc.).
Chaque fois que je suis un peu confus ou chaque fois que quelqu'un me pose une question sur une section de code, j'essaie de le corriger pour que cela ait du sens.
Cela peut être aussi simple que d'ajouter un commentaire pour supprimer un ensemble d'opérations déroutant dans leur propre fonction ou déclencher un refactoriseur plus important, comme l'extraction d'un nouvel objet.
Je vous suggère d'encourager tous les membres du groupe à "s'approprier" que leur code est lisible par les autres - cela signifie que chaque fois que quelqu'un vous pose une question à propos de votre code, vous vous engagez à apporter un changement - ou mieux encore, associez-le à cela personne pour faire le changement dès maintenant!
Envisagez sérieusement de faire pression pour que cela fasse partie de votre "contrat d'équipe" (et créez définitivement un contrat si vous n'en avez pas) - de cette façon, tout le monde est d'accord et vous l'avez accroché quelque part sur un mur pour qu'il n'y ait pas '' t aucune question sur ce que vous avez accepté de faire.
De nombreux projets nécessitent une documentation de code: document d'interface, document de conception, ...
Certains projets nécessitent qu'une telle documentation soit placée dans les commentaires de code et extraite avec des outils comme Doxygen ou Sphinx ou Javadoc, afin que le code et la documentation restent plus cohérents.
De cette façon, les développeurs sont tenus d'écrire des commentaires utiles dans le code et cette tâche est intégrée dans la planification du projet.
Si vous suivez une bonne norme de codage, il y aura un nombre minimum de commentaires requis. les conventions de dénomination sont importantes. Les noms de méthode et les noms de variable doivent décrire leur rôle.
Mon TL me suggère d'utiliser moins de commentaires. il veut que mon code soit compréhensible et auto-descriptif. exemple simple: nom de variable pour le type de chaîne utilisé pour le modèle de recherche
var str1:String="" //not uderstandable
var strSearchPattern:String="" //uderstandable
Je vais dire ce que la plupart des réponses et commentaires suggèrent: vous devez probablement comprendre le vrai problème ici plutôt que d'essayer de pousser votre solution perçue à travers.
Vous êtes motivé à voir des commentaires dans son code; pourquoi? Vous avez donné une raison; pourquoi cette raison est-elle si importante pour vous? Il est plus motivé à faire autre chose à la place; pourquoi? Il donnera une raison; pourquoi cette raison est-elle si importante pour lui? Répétez cette opération jusqu'à ce que vous arriviez au niveau où le conflit survient réellement et essayez d'y trouver une solution avec laquelle vous pourrez vivre tous les deux. Je parie que cela a très peu à voir avec les commentaires.
Peut-être que ce type doit avoir une appréciation de la bonne discipline de codage et pourquoi il est important pour les autres de comprendre le code qu'il a écrit.
J'ai travaillé sur des bases de code vraiment horribles dans ma carrière, celles où le code était si mal organisé, les noms de variables étaient si pauvres, les commentaires si mauvais ou inexistants, que la base de code a nui à ma productivité. Vous ne pouvez pas travailler pour corriger ou améliorer une base de code que vous ne comprenez pas, et si elle est écrite d'une manière qui est impénétrable pour les nouveaux arrivants, ils passeront plus de temps à essayer de la comprendre qu'à travailler dessus.
Il n'y a pas de meilleur professeur qu'une dure expérience!
Chaque base de code contient des morceaux horribles, des parties du système que personne ne veut toucher parce qu'ils ont peur de casser quelque chose, ou ils ne peuvent pas faire de travail significatif parce que celui qui a écrit le code est parti depuis longtemps et a pris leur compréhension du code avec eux. Si ce code n'est pas commenté et n'est pas auto-documenté, cela ne fait qu'empirer les choses.
Je vous suggère de trouver le morceau de votre base de code qui est comme ça, et d'en confier la responsabilité à votre codeur gênant. Donnez-lui la propriété, faites-en sa responsabilité, laissez-lui apprendre la vraie douleur de travailler sur du code qui ne peut pas être maintenu parce qu'il n'est pas bien documenté ou impossible à comprendre dans un court laps de temps. Après quelques mois à y travailler, je suis sûr qu'il va commencer à revenir.