Comment puis-je traiter avec un membre de l'équipe qui n'aime pas faire des commentaires dans le code?


184

Un membre de mon équipe évite systématiquement de faire des commentaires dans son code.

Son code n'est pas auto-documenté et les autres programmeurs ont du mal à comprendre son code.

Je lui ai demandé à plusieurs reprises de commenter son code, mais il ne fait que donner des excuses ou prétend qu'il le fera plus tard. Son inquiétude est que l'ajout de commentaires prendra trop de temps et retardera les projets.

Quel argument puis-je lui présenter pour le convaincre de documenter correctement son code?

Sur cette note, ai-je tort de me concentrer sur les commentaires du code ou est-ce une indication d'un problème plus vaste qui devrait être résolu?


109
Faire des commentaires à des fins de commentaires ne rend pas le code meilleur. Si le code est compréhensible (y compris pourquoi) sans commentaires, sinon, commentez.
Martin York

63
Oh oui, et quand la complexité d'un code triple pour résoudre une situation de concurrence critique ou une impasse, ne commentez pas cela! Laissez les gens résoudre le problème de savoir pourquoi le code doit être tel qu’il est, et pourquoi il rompt de manière mystérieuse s’ils apportent des modifications expérimentales. Tout le monde devrait être un grand maître d'échecs de la concurrence ...
Kaz

12
@Kaz Sarcasm (j'espère) ne traduit pas bien en texte.
deworde

10
@deworde & artjom - oui, c'est du sarcasme. non, cela ne semble pas aussi net que possible, mais c'est clairement un sarcasme.

17
En suivant le principe de Dale Carnegie, vous devriez essayer de comprendre pourquoi il ne veut pas commenter. Vous avez mentionné qu'il ne voulait pas retarder le projet. capable de comprendre le code et qui retarderait encore le projet .. cela devrait certainement aider ..
Anirudha

Réponses:


431

Les commentaires seuls ne permettent pas d'obtenir un meilleur code, et le simple fait de demander "plus de commentaires" ne vous donnera guère plus que /* increment i by 1 */des commentaires de style.

Alors demandez-vous pourquoi vous voulez ces commentaires. "C'est une bonne pratique" ne compte pas comme argument, sauf si vous comprenez pourquoi.

Maintenant, la raison la plus frappante pour utiliser des commentaires est que le code est plus facile à comprendre. Lorsque les gens se plaignent du manque de commentaires, ils sont soit des perroquets sans intelligence, soit ils ont du mal à comprendre le code avec lequel ils travaillent.

Donc, ne vous plaignez pas des commentaires manquants, mais 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 du code illisible, vous poserez simplement plus de questions. Et si vous revenez plus tard à un morceau de code et que vous ne savez pas si vous vous en souvenez bien, posez la même question à nouveau.

Si les commentaires peuvent résoudre le problème et que votre collègue a un cerveau fonctionnel, il / elle se rendra compte qu'il est beaucoup plus facile de commenter le code que de vous laisser poser des questions stupides tout le temps. Et si vous ne pouvez pas poser de questions, alors peut-être que le code est déjà parfaitement lisible et que 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 interpersonnelles, évitez de paraître condescendant ou accusateur à tout prix; soyez sérieux et honnête dans vos questions.


269
+1 pour "ne pas se plaindre de commentaires manquants: se plaindre de code illisible."
Md Mahbubur Rahman

4
Que se passe-t-il si la réponse à une question sur le code va dans le sens de "Qu'avez-vous fait pour le comprendre?"
Saul

40
+1: Pousser pour des noms de fonction lisibles peut avoir des avantages supplémentaires ... Lors de la révision du code: "Impossible de comprendre ce que fait xg_jkhsfkasq". "Oh, il est en train de vider le tampon d'alimentation principal, puis-je le libérer?" "Bien sûr, mais j'hésite à l'approuver jusqu'à ce que vous ayez renommé la fonction flush_primary_buffer" "Ah, mais c'est aussi vider le cache principal, donc ce nom serait trompeur" "C'EST QUOI? N'effacez pas ce cache, ça Arrêtez le système! Pendant que vous modifiez cette logique, voudriez-vous renommer cette fonction? "
deworde

18
J'aurais peur de donner l'impression que je suis incapable de lire du code. Un responsable non technique peut simplement remarquer que je demande constamment de l'aide à «Bob» car son code est trop avancé pour moi. Cela voudrait dire que Bob est un développeur «avancé» et que je ne suis pas prêt à travailler à son niveau.
Rob P.

5
@Rob P. Je vois la peur, mais si vous ne pouvez pas lire le code et qu'il est prévu de le conserver, alors le code n'est pas bien écrit ou vous en savez trop peu. Si vous ne savez pas assez, vous devez demander. Si demander révèle que le code est simplement difficile à lire, faites-le réparer. Le truc serait que, si vous suivez la voie de l'ingénierie sociale, mélangez si Bob va à votre bureau ou vous allez chez lui, et soyez très actif pour indiquer les choses. Après tout, un responsable non technique ne sera pas en mesure de saisir le contenu de la discussion ...
deworde

114

J'ai rencontré de nombreux développeurs qui avaient du mal à écrire du code auto-documenté ou des commentaires utiles. Ces personnes manquent souvent de suffisamment d'autodiscipline ou d'expérience pour bien faire les choses.

Ce qui ne marche jamais, c'est "leur dire d'ajouter plus de commentaires". Cela n'augmentera ni leur autodiscipline ni leur expérience. IMHO la seule chose qui pourrait fonctionner est de faire des revues de code et des sessions de refactoring fréquentes. Lorsqu'un développeur a terminé une tâche, laissez-le lui 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 six mois plus tard.

Faites cela sur une période de quelques mois, au moins deux fois par semaine. Si vous êtes assez chanceux, les autres développeurs apprendront à travers ces sessions afin que vous puissiez réduire la fréquence de révision.


5
+1 c'est la seule façon d'implémenter les changements chez un collègue que j'ai trouvé, asseyez-vous avec eux et examinez / modifiez à leurs côtés. Si vous n'êtes pas en mesure de refuser une révision de code, cela peut être difficile. Parfois, lorsque vous êtes à mi-parcours, vous devez simplement poser des questions aux aînés et s'ils n'écoutent pas, ne vous laissez pas aller jusqu'à ce qu'ils soient plus âgés et qu'ils puissent opposer leur veto à de telles ordures
Jimmy Hoffa

1
Les revues de code et la programmation en paire sont le meilleur moyen, selon mon expérience, d’améliorer le niveau général des développeurs dans une équipe. Il s’agit de partager connaissances et compétences au sein de l’équipe. Sans cela, vous aidez les développeurs à apprendre à la dure et en supposant qu'ils soient parfaitement parfaits. L'absence générale de cette pratique dans l'industrie est probablement la raison pour laquelle il y a tant de développeurs ayant plus de 10 ans d'expérience qui ne peuvent pas écrire de code lisible et bien organisé.
Martin Brown

27

Je suis surpris que personne n'ait encore mentionné les critiques de code. Faire des critiques de code! Quand il a un enregistrement de mauvaise qualité, ne dites pas simplement "ajouter des commentaires". Posez constamment des questions et demandez-lui de vous dire ce que fait son code et pourquoi. Prendre des notes. Ensuite, à la fin de l'examen du code, donnez-lui une copie des notes et dites-lui de rendre vos questions assez évidentes. Soit par plus de commentaires ou simplement en refacturant son code pour le rendre de meilleure qualité (de préférence ce dernier si possible)


2
+1 - Si vous devez poser une question sur une partie du code, cette partie nécessite soit un commentaire, soit une refactorisation afin que la question n'ait plus à être posée à quelqu'un d'autre.
Dunk

+1 Les évaluations de code / peer surprises sont également très basses dans les réponses. Mettre en œuvre des révisions de code au niveau de l’équipe (afin de ne pas choisir un individu) pourrait aider à résoudre le problème (et peut-être d’autres que vous ne saviez même pas que vous avez :). Dans les cas extrêmes, vous pouvez mettre en œuvre une politique de non-solo-push qui interdit de pousser si les modifications ne sont pas révisées par un autre membre de l'équipe.
Chris Lee

@ChrisLee chez mon entreprise, les règles de révision du code de l'entreprise ne sont pas appliquées techniquement, mais il existe une règle selon laquelle un article ne peut pas être marqué comme étant prêt à être testé, il doit être révisé en fonction du code, quel que soit l'auteur du travail de développement. C'est assez intéressant d'avoir à réviser le code lorsque le CTO effectue un enregistrement bien que lol
Earlz

18

Cela dépend du code produit par votre collaborateur. Si vous lisez le livre sur le code propre d'Oncle Bob, vous constaterez qu'il préfère ne pas ajouter de commentaires au code. Si le code lui-même est aussi lisible qu'il devrait l'être, il n'est guère nécessaire de faire des commentaires.

Si ce n'est pas le cas, ou si vous avez besoin de commentaires en raison d'une politique non négociable, la question principale est de savoir si c'est seulement vous qui voulez lui écrire des commentaires, ou si c'est toute l'équipe ou l'équipe / le projet chef. Si ce n'est que vous, alors vous devriez parler à vos autres collègues pour savoir pourquoi ce n'est peut-être pas si grave.

Si le chef de projet manque de commentaires, vous pouvez également les demander dans le cadre de son caractère complet , c'est-à-dire que si le code soumis manque de commentaire, le travail n'est pas encore terminé. Il ne peut pas continuer à faire d'autres travaux tant que son travail actuel n'est pas terminé et que des commentaires sont nécessaires. Cependant, gardez à l'esprit que ce type de forçage donnera probablement lieu à des commentaires horribles (attendez-vous à des tas de commentaires de code répétés de mauvaise qualité).

À mon humble avis, le seul moyen envisageable est de discuter des bénéfices réels que vous et tous les autres retirons des commentaires. Si il / elle ne comprend pas cela par simple discussion, il y a toujours une solution: vous ne les laissez pas écrire du nouveau code, mais faites-les travailler sur le code existant. Si possible, vous devriez leur trouver deux zones de travail différentes: l’une avec les commentaires utiles et l’autre sans commentaires. Le fait de devoir lire le code non commenté non lisible de quelqu'un d'autre vous ouvre les yeux sur votre propre travail.

Nous sommes tous passés par là une fois et étions fâchés contre l'auteur original d'une source pour avoir travaillé si bâclée. C’est la réflexion supplémentaire que chacun de nous est également un tel auteur qui vous fait comprendre que vous devez vous soucier de la lisibilité - n’oubliez donc pas de discuter des résultats avec votre collègue par la suite afin de promouvoir cette réflexion.


+1 pour discuter des bénéfices réels des commentaires. Les commentaires sont censés ajouter de la valeur au code source.
Sparky

1
Re: "ce genre de forçage entraînera très probablement des commentaires horribles". Si vous ne commentez pas pendant que vous codez, le remplissage des commentaires une fois le code terminé entraînera presque toujours des commentaires horribles, que vous y croyiez ou non. Lorsque vous codez, c’est le moment où vous savez exactement POURQUOI vous faites quelque chose d’une manière particulière. C'est le moment de laisser les autres savoir. Si vous commentez une fois que vous avez terminé, il est fort probable que vous ne vous souveniez même pas de ce que vous pensiez lorsque vous avez écrit le code. Vous avez donc tendance à ajouter un commentaire inutile à des fins de commentaire.
Dunk

3
toujours eu un problème avec l'approche de ce livre. Les commentaires peuvent être très utiles pour expliquer un processus métier / une logique (ou pourquoi) qu'aucune quantité de code propre ne peut.
Bharal

Bien que les commentaires dans le code ne soient pas nécessaires, il devrait au moins y avoir une description de la méthode, telle que Javadoc
Danubian Sailor

2
Clean Code est un livre décent, mais il ne devrait pas être traité comme un évangile. Vous devez appliquer le bon sens et décider vous-même ce qui fonctionne. Je ne suis pas d'accord avec les conseils sur les commentaires, car les langages de programmation sont conçus pour exprimer le comment d'un problème sans se soucier du pourquoi. J'écrivais un code pour Google Shopping qui ajoute un code de pays à la référence du produit. Ce que le code fait est évident, mais à moins que vous sachiez que vous ne pouvez utiliser le même code de produit qu'une seule fois, même sur des marchés différents, vous ne sauriez pas pourquoi je le faisais. Le commentaire que j'ai ajouté le clarifie.
GordonM

10

Si vous avez un employé qui ne peut pas suivre les instructions, réprimandez-le et assurez-vous qu'il est clair que cela ne l'aidera pas. La cohérence du style de codage est essentielle pour une équipe. Si tout le monde écrit des commentaires alors que ce n'est pas le cas, le style de codage en souffrira.

Cela dit, vous pouvez probablement l'aider. D'après mon expérience, quand quelqu'un proteste que le commentaire prend trop de temps, il existe un obstacle psychologique tel que…

  1. Il est conscient de ses choix de code et de conception et ne veut pas les exposer en prose. (Les révisions de code peuvent être utiles pour renforcer la confiance en soi de quelqu'un tout autant que pour le démolir.)
  2. Il travaille de manière très linéaire et ne pense pas beaucoup en avance. Commenter est pénible, car cela l'oblige à décharger de sa mémoire de travail le code immédiat qu'il était sur le point d'écrire afin de composer son intention de manière différente. (Si cela est vrai, le commentaire devient très important pour la qualité de son code.)
  3. Historiquement, les gens ne comprennent pas ses commentaires.

Il est important qu'un programmeur se rende compte que les commentaires ressemblent à des tests: ils ne sont pas destinés uniquement à un usage futur, ils sont destinés au programmeur lui-même. Ils le forcent à penser différemment à son approche.

Rien de tout cela ne remplace les avis de CI, les tests ou les révisions de code. Ce n’est qu’un des nombreux aspects critiques du codage qui, en soi, ne consiste pas à écrire du code.


3
Je ne pense pas que les menaces vont nécessairement être efficaces, elles peuvent apparaître comme de l’intimidation (même si ce n’était pas l’intention) et les codeurs ont tendance à avoir tendance à ressentir du ressentiment envers les édits de plus haut placés. Dans ce cas, creuser ses talons encore plus. Cela peut venir en dernier recours, mais seulement en dernier recours.
GordonM

@GordonM Pensez-vous qu'il serait préférable de ne pas informer un employé lorsque son comportement est inapproprié, et quelles seraient les conséquences d'un comportement inapproprié continu?
Kojiro

Ne rien dire du tout n'est évidemment pas une bonne idée, mais menacer les gens ne fera que créer un climat de peur, en particulier pour une chose relativement mineure telle que le style de commentaires. Si vous lui expliquez raisonnablement pourquoi l’équipe juge important de commenter, c’est bien. Mais je sais que si quelqu'un me menaçait de licencier quelque chose d'assez mineur, je serais plus enclin à commencer à chercher un autre emploi.
GordonM

@GordonM En fait, je ne suis pas d'accord avec l'hypothèse selon laquelle ce que j'ai dit menaçait, mais j'ai quand même résolu le problème.
kojiro

8

Obtenez un logiciel de révision de code et utilisez-le bien.

Nous utilisons Kiln et nous l'aimons. Nous avons pour politique de réviser chaque ensemble de modifications (bien que nous permettions aux développeurs de créer / approuver des révisions pour eux-mêmes sur les balises et les fusions sans conflit (bien que la plupart d'entre nous utilise rebaseif); ainsi, nous pouvons rapidement repérer les ensembles de modifications sans révisions).

Un code qui n'est pas clair est la raison pour laquelle une révision de code doit être rejetée. Peu importe que le correctif soit un commentaire ou un code plus clair, mais le relecteur doit pouvoir le comprendre. Certains développeurs préfèrent réécrire le code, mais d'autres (moi-même inclus) trouvent souvent plus facile d'exprimer une 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. Il faut que ce soit clair pour une autre personne.

En utilisant un logiciel tel que Kiln, aucune modification n’est négligée. Tout le monde dans mon équipe de développeurs le préfère beaucoup de cette façon. Le logiciel de révision de code a eu un impact considérable sur la qualité de notre code et la qualité de nos 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 a pas fallu longtemps pour comprendre que les choses sont meilleures de cette façon et qu'ils l'acceptent :-)

Il est également intéressant de noter que nous essayons de ne pas obliger les développeurs à expliquer le code cryptique de manière verbale ou dans les commentaires de la revue. Si quelque chose n'est pas clair, le meilleur endroit pour l'expliquer est dans le code (dans les commentaires ou par refactoring), puis ajoutez les nouveaux ensembles de modifications à la même révision.


4

Il est intéressant de noter que la lisibilité appliquée au langage naturel se mesure à la vitesse de lecture et de compréhension. J'imagine 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, les langages de programmation haut de gamme peuvent éviter la programmation "sur-documentée" superflue (de code) en utilisant des éléments du langage lui-même. Il est également déconseillé de transformer le code en une liste à partir de textes de programmation où les déclarations individuelles sont littéralement expliquées de manière presque tautologique (gardez à l’esprit l’exemple "/ * incrémenté de 1 * /" dans les réponses déjà fournies), ce qui rend ces commentaires pertinents. aux programmeurs inexpérimentés avec la langue.

Néanmoins, l'intention est d'essayer de commenter le code "sous-documenté" (mais dénué de sens) qui est vraiment "la source de tout mal". L'existence même d'un code "sous-documenté" est un mauvais signal - qu'il s'agisse d'un gâchis non structuré ou d'un mot délirant à caractère mystique. De toute évidence, la valeur de ce code est au moins discutable. Malheureusement, il y a toujours des exemples, quand il est en effet préférable d'introduire un commentaire dans une section de lignes de code formatées (regroupés visuellement) plutôt que de l'envelopper dans un nouveau sous-programme (gardez à l'esprit la "consistance stupide" qui "est le lutin des petits esprits") .

Lisibilité du code! = Commentaires du code

Le code lisible ne nécessite pas d’annotations par commentaires. À chaque endroit particulier du code, il y a toujours un contexte de tâche que ce code particulier est censé réaliser. Si le but manque et / ou si le code fait quelque chose de mystérieux = évitez-le à tout prix. Ne laissez pas de hacks bizarres peupler votre code - c'est le résultat direct de la combinaison de technologies buggy et de manque de temps / d'intérêt pour comprendre les fondements. Évitez le code mystique dans votre projet!

D'autre part, Readable programme = code + documentation peut contenir plusieurs sections de commentaires légitimes, par exemple pour faciliter la génération de documentation "commentaires dans l'API".

Suivre les normes de style de code

Assez drôle, la question n'est pas de savoir pourquoi commenter du code, mais bien de travailler en é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, qui soit trop "personnel" et "subjectivement" ambigu. Donc, je suppose que si on voit la nécessité d’utiliser le style de code, il existe toute une série d’outils permettant de le mettre en œuvre correctement - en commençant par l’éducation des personnes et en terminant par l’automatisation pour le contrôle de la qualité du code (nombreuses notes, etc.) et (révision). systèmes de contrôle de code intégrés).

Devenir un évangéliste à la lisibilité du code

Si vous acceptez, ce code est lu plus souvent qu'il n'est écrit. Si une expression claire des idées et de la pensée sont clairement importantes pour vous, quelle que soit la langue utilisée pour communiquer (mathématiques, code machine ou ancien anglais) .. Si votre mission est d'éradiquer toute forme de pensée alternative terne et laide .. (désolé , le dernier provient d’un autre "manifeste") .. posez des questions, initiez des discussions, commencez à diffuser des livres stimulants sur le nettoyage de code (probablement non seulement quelque chose de similaire aux modèles de Beck, mais plus similaire à celui déjà mentionné par RC Martin ) qui aborde l’ambiguïté en programmation. Plus loin, passage d'idées clés (cité dans le livre de O'Reilly sur la lisibilité)

  • Simplifiez l'attribution de nom, les commentaires et le formatage avec des astuces 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 coupant les "commentaires", il en reste encore beaucoup (j'imagine qu'écrire du code qui n'a pas besoin de commentaires est un excellent exercice!). Nommer des identificateurs sémantiquement significatifs est un bon début. Ensuite, structurez votre code en regroupant des opérations connectées logiquement en fonctions et en classes. Etc. Un meilleur programmeur est un meilleur écrivain (bien sûr, en supposant que d'autres compétences techniques soient données).


Vous pouvez écrire du code qui n'a pas besoin de commentaires uniquement pour le plaisir. C’est peut-être un bon exercice, mais pas si vous devez revenir au code et ne pouvez rien changer car vous ne saurez pas pourquoi cette fonction fonctionne comme elle le fait peut-être qu’un client l’a voulu comme ça. Bien sûr, il se peut que 1% des projets soient documentés et raisonnés en dehors du projet, mais même dans ce cas, certaines décisions que vous prenez lors du codage ne sont pas renvoyées à la documentation. Et franchement ... Qui lit une documentation qui ne se trouve pas dans le code. Certainement pas les programmeurs ;-P.
Nux

1
Un bon ingénieur se préoccupe de l’ensemble du système (y compris de la documentation non générée par le code) - mais ici, bien sûr, il s’agit de coder de manière générale. Mon problème est que le fait de ne pas avoir d’identificateurs dans le code appelé foo , bar , tmpSomething2 et IamJustTooSmartAssToCare améliore déjà réduit la nécessité générale d’expliquer ce que le code est et ce qu’il fait. Le code doit être écrit avec le "mode de réflexion activé" comme une API bien conçue qui est lue, comprise, réutilisée et maintenue par les humains. Trop de commentaires en code, autrement difficiles à comprendre, sont un très mauvais signe!
Yauhen Yakimovich

BTW programmant / encodant n’importe quel type de logique spécifique à un domaine sous la forme d’un HACK ou d’un correctif de bogue "temporaire" produit en fait des "HACKs étranges" - dès que vous en avez beaucoup inséré dans la boîte noire - attendez-vous à ce qu'ils le soient échouer et riposter. Cela peut être justifié par des délais dans les projets du "monde réel", etc. mais en réalité, il s’agit d’un logiciel bon marché qui nécessite un remodelage de la logique de domaine (ou peut-être un nouveau travail).
Yauhen Yakimovich

Je conviens que la lisibilité est importante. Ce que je ne partage pas, c'est que vous semblez dire "si vous faites de la lisibilité une priorité, vous n'aurez pas besoin de commentaires". Ce n'est tout simplement pas vrai. Été fait ça. Raisonner ce que vous faites ne vient pas simplement de nommer des variables d’une manière sensée. Faites cela bien sûr, mais ajoutez également une raison dans les commentaires (même s'il s'agit d'un bogue / d'une exigence / d'un numéro d'histoire dans un système externe). C'est ce que je dis.
Nux

"si vous faites de la lisibilité une priorité, vous n'aurez pas besoin de commentaires" - oui, c'est exactement ce que je dis (et je suis conscient que cela ne semble pas facile à réaliser). BTW Avez-vous des situations où maintenir complet l'historique de validation (contrôle de version) n'est pas suffisant pour réfléchir sur "numéro de bogue / exigence / histoire"? Je pratique depuis assez longtemps - travaille pour moi et permet de garder le code vide de l’histoire du développement ... le rend moins organique.
Yauhen Yakimovich

3

Ai-je tort de me concentrer sur les commentaires du code ou est-ce un indice d'un problème plus grave 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 revues / sessions de refactoring sont une bonne idée. Je trouve la programmation en binôme encore plus efficace, mais elle peut aussi être beaucoup plus difficile à mettre en œuvre.


La programmation en binôme est une excellente idée, elle donne à un autre programmeur un aperçu du développement du code afin qu’il sache ce qui se passe, ce qui permet à deux personnes de rendre compte du code. cela donne également la chance à l’un des deux de dire que quelque chose doit avoir un commentaire parce qu’il est hors de l’ordinaire ou quelque chose que quelqu'un d'autre pourrait changer parce que ça ressemble à ... "une fuite de mémoire", "un mauvais code", etc. certaines choses ont besoin d'être commentées pour que quelqu'un à l'avenir n'annule pas quelque chose parce que cela ne semble pas correct.
Malachi

3

Tout d'abord, je vous suggérerais de reformuler votre approche concernant les commentaires.

S'il s'agit de commentaires de documentation au niveau de l'API (exposés ultérieurement au public), alors 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 diaboliques. Je recommanderais de lire le chapitre sur les 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 à maintenir. 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 lire le code à la place. 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 hash 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!


4
C'est juste idiot. J'espère que personne ne croit qu'un tel style de commentaire est utile. Mais croyez-vous honnêtement que les commentaires ne devraient jamais être utilisés?
Jmk

1
Oui, c'est une suggestion idiote, si le code est incroyablement lisible, je peux comprendre quelques commentaires, mais voir des commentaires devrait indiquer pourquoi la méthode fonctionne telle qu'elle est et où elle sera utilisée une fois que vous aurez dépassé plusieurs classes. aucune raison pour aucun commentaire, ils aident tout le monde.
DBlackborough

3
La chose importante à retenir est que, bien que tout ait du sens pour vous en ce moment, quelqu'un d'autre devra gérer votre code dans 3 ans. Ne vis pas le dessus.
xaxxon

4
@xaxxon Sans parler de pommes, même si cette personne est peut-être vous.
moelleux

3
@mehaase - Pas quoi, pas comment, mais pourquoi est la raison la plus importante pour ajouter des commentaires au code.
Henk Langeveld

1

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 pouvoir savoir qui a écrit le code original (tout système de contrôle de révision sain) et devrait être encouragé à demander à l'auteur du code de l'expliquer directement (par exemple, se rendre à 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 faite; et (s'ils sont intelligents) commenceront à ajouter des commentaires pour éviter de perdre du temps sur toutes ces explications.

Notez qu'encourager les membres de l'équipe à se demander mutuellement des explications est précieux 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.

Généralement, en encourageant les membres de l'équipe à se demander mutuellement des explications, vous créez un système d'équilibrage automatique. où différents membres de l'équipe "s'ajuste automatiquement" les uns aux autres.


1

Ceci est en grande partie une extension de la réponse, mais effectue des révisions de code à intervalles réguliers.

Le faire asseoir avec lui (et les autres développeurs), parcourir leur code et plus ou moins défendre devant leurs supérieurs et leurs pairs rendra chacun meilleur codeur et ajoutera de la valeur réelle sur une période relativement courte. À court terme, le développeur en question n'aura aucune excuse pour, au moment de la révision, commenter correctement son code.

EDIT: Je ne suis pas sûr de la raison pour laquelle quelqu'un suggèrerait de changer ma suggestion - peut-être que j'ai pris pour acquis que les avantages de la révision de code seraient de notoriété publique ... veuillez consulter ce fil pour une analyse communautaire de la pratique:

Le code passe-t-il en revue les bonnes pratiques?


Quand une pièce remplie de monde commence à rire de votre code illisible, vous commencez à faire un meilleur travail de codage et de commentaire. :) Je suis un grand partisan des critiques de code.
Evik James

1
Faire en sorte que les gens rient du code devant d'autres collègues n'est pas la solution: - \
Danny Tuppeny

1
Si les personnes chargées de la révision de code rigolent plutôt qu'elles ne sont constructives, elles ont tout autant besoin de formation que les développeurs qui ne peuvent pas écrire de code lisible. Donner des critiques constructives plutôt que dérogatoires est l’une des compétences sociales qui manque souvent aux développeurs.
Martin Brown

1

Compte tenu des points de vue souvent extrêmes sur les commentaires, j’hésite à intervenir. Cela dit ...

Quels sont certains des arguments que je peux présenter, à savoir que si vous allez écrire du code (illisible), il doit ê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 beaucoup d’expérimentés) souffrent souvent de l’effet Ikea ( PDF ). C'est parce qu'ils l'ont construit et le connaissent très bien, et ils sont sûrs que le code est non seulement génial, mais lisible également.

Si la personne est un grand programmeur, alors peu ou pas de documentation est nécessaire. Cependant, la plupart des programmeurs ne sont pas géniaux et beaucoup de leur code va souffrir dans le département "lisibilité". Il est utile de demander au programmeur médiocre ou en développement d '"expliquer son code", car cela l'oblige à visualiser son code avec un œil plus critique.

Est-ce que cela signifie "documenter" leur code? Pas nécessairement. Exemple, j'ai eu 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 critiques de code auraient été plus utiles.

Vous (ou un délégué) devriez vous asseoir avec ce programmeur et extraire une partie de son ancien code. Pas les nouvelles choses qu'il connait juste en travaillant dessus. Vous devriez lui demander de vous expliquer son code avec une interaction minimale. Cela pourrait aussi être une session séparée de "documentation", où il expliquera par écrit son code. Ensuite, il devrait avoir des retours sur de meilleures approches.

Soit dit en passant, il est parfois nécessaire de disposer de documentation, quelle que soit la qualité de "lisibilité" du code. Les API doivent avoir une documentation, les opérations extrêmement techniques et complexes devraient aider le programmeur à comprendre les processus impliqués (souvent en dehors du domaine de connaissances du programmeur), et certaines choses comme les expressions rationnelles complexes devraient vraiment documenter ce qui vous correspond.


0

De nombreux projets nécessitent une documentation de code: document d'interface, document de conception, ...

Certains projets exigent que cette documentation soit insérée dans des commentaires de code et extraite à l'aide d'outils tels que Doxygen, Sphinx ou Javadoc, afin que le code et la documentation restent plus cohérents.

De cette manière, les développeurs doivent écrire des commentaires utiles dans le code et cette obligation est intégrée à la planification de projet.


6
Non, les développeurs doivent alors écrire des commentaires. Leur utilité décroît avec la pression pour les écrire, tombant souvent au- dessous de zéro dans la région activement nuisible (le commentaire invalide est pire que l'absence de commentaire) si la stratégie est poussée fortement.
Jan Hudec

1
@ JanHudec - Je suis d'accord avec vous. C'est pourquoi un certain contrôle devrait être défini. La génération automatique garantit, par exemple, que les arguments de fonction dans le code sont les mêmes que dans les commentaires. De plus, le fait d'avoir un seul PDF au lieu d'un répertoire de fichiers source rend la documentation plus lisible (c'est-à-dire plus révisable) par plus de personnes.
mouviciel

2
Eh bien non. Comment allez-vous remarquer dans le .pdf que le code fait quelque chose de subtilement différent de ce que dit la description?
Jan Hudec

1
Peut-être que mon opinion est biaisée par mon domaine, un logiciel essentiel dans l’espace, dans lequel tout est revu, contrôlé, vérifié, testé deux ou trois ou quatre fois. La génération automatique de documentation ne supprime pas les incohérences mais aide à les réduire.
mouviciel

Oui, vous êtes fortement biaisé. Dans de tels domaines, il est logique que la plupart des tests unitaires soient suffisants pour l'assurance qualité et que documenter chaque dernière fonction soit une perte de temps.
Jan Hudec

0

Je vais exposer ce à quoi la plupart des réponses et commentaires font allusion: vous avez probablement besoin de comprendre le vrai problème ici plutôt que d'essayer de pousser votre solution perçue jusqu'au bout.

Vous êtes motivé pour voir les 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 va donner 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 de trouver une solution à ce problème avec laquelle vous pourrez vivre tous les deux. Je parie que cela a très peu à voir avec les commentaires.


0

Si vous suivez une bonne norme de codage, un nombre minimum de commentaires sera requis. les conventions de nommage sont importantes. Les noms de méthodes et les noms de variables 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 motif de recherche

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

0

J'adore les réponses à l'examen du code, mais mon processus aidera peut-être aussi un peu.

J'adore les commentaires, mais je ne les ajoute presque jamais dans le code lors du premier passage. C’est peut-être juste mon style, mais je vais toucher la même section de code 3 à 5 fois au cours du développement (refactorisation, écriture de tests, etc.).

Chaque fois que je suis un peu confus ou que quelqu'un me pose une question sur une section de code, j'essaie de la corriger pour qu'elle ait un sens.

Cela peut être aussi simple que d'ajouter un commentaire supprimant un ensemble d'opérations déroutant dans leur propre fonction ou de déclencher un refactor plus grand, comme l'extraction d'un nouvel objet.

Je suggère que vous encouragiez tous les membres du groupe à "reconnaître" que leur code est lisible par les autres - cela signifie que chaque fois que quelqu'un vous pose une question sur votre code, vous vous engagez à apporter un changement - ou, mieux encore, à l'appariement personne à faire le changement à droite alors!

Envisagez sérieusement de faire pression pour cela dans le cadre de votre "contrat d'équipe" (et créez définitivement un contrat si vous n'en avez pas) - de cette manière, tout le monde est d'accord et vous l'avez sur un mur quelque part pour qu'il n'y Aucune question sur ce que vous avez accepté de faire.


0

Peut-être faut-il donner à ce type une idée de la discipline en matière de codage, et expliquer pourquoi il est important que les autres puissent comprendre le code qu'il a écrit.

J'ai travaillé sur des bases de code vraiment terribles dans ma carrière, celles où le code était si mal organisé, les noms de variables tellement pauvres, les commentaires si mauvais ou inexistants que la base de code a nui à ma productivité. Vous ne pouvez pas travailler pour réparer ou améliorer une base de code que vous ne comprenez pas, et si elle est écrite de manière impénétrable pour les nouveaux arrivants, ils passeront plus de temps à essayer de comprendre que de travailler dessus.

Il n'y a pas de meilleur professeur qu'une expérience dure!

Chaque base de code contient des éléments horribles, des parties du système que personne ne veut toucher, car ils ont peur de casser quelque chose, ou ils ne peuvent pas faire de travail significatif, car ceux qui ont écrit le code sont partis depuis longtemps et ont bien compris. du code avec eux. Si ce code n'est pas commenté et n'est pas auto-documenté, il ne fait qu'aggraver les choses.

Je vous suggère de trouver le morceau de votre code qui est comme ça et d'en donner la responsabilité à votre codeur gênant. Donnez-lui la propriété, faites-en sa responsabilité, laissez-lui apprendre la vraie peine de travailler sur du code qui ne peut pas être maintenu car il n'est pas bien documenté ou impossible à comprendre en peu de temps. Après quelques mois de travail, je suis sûr qu'il va commencer à arriver.


-1

Donnez-lui un autre code sans commentaires et demandez-lui de comprendre le code. Peut-être comprend-il l’importance des commentaires appropriés à ce moment-là.


12
J'ai à peine évité le bouton -1 à ce sujet. La plupart du code que j'écris a très peu de commentaires. Je ne pense pas que des gens se soient plaints du fait que cela n’était pas compréhensible au moins au cours des dernières années. À de très rares exceptions près, si le code nécessite la compréhension des commentaires , il n'a pas besoin de commentaires, il doit être amélioré pour plus de clarté. (Bien sûr, vous devez assumer la compréhension de base de la syntaxe du langage. Des choses comme, en C ++, ne vous dérangez pas simplement pour éviter d’utiliser, reinterpret_cast<>()parce que les gens peuvent trouver cela déroutant; en C #, si c’est ??ce dont vous avez besoin, utilisez etc.)
un CVn

2
@ MichaelKjörling: Cela peut dépendre énormément du type de code que vous écrivez. Si votre code dépend de caractéristiques inhabituelles d'un langage ou d'une API, ou si vous avez agi de manière contre-intuitive afin d'éviter un bogue obscur qui vous a pris des heures à découvrir, il serait beaucoup plus efficace de commenter Il est plus facile que d’essayer de rendre le code "clair" à propos de cette information de base sans commentaires.
LarsH

@ MichaelKjörling: Je suis particulièrement motivé pour le dire aujourd'hui parce que je lutte depuis un mois avec une API SIG profonde. Les installations de l'API sont complexes et ne sont pas très documentées. Nous rencontrons constamment des surprises, dont certaines nous retardent de plusieurs jours. S'attendre à ce que quelqu'un d'autre (ou moi dans 6 mois) doive redécouvrir ces pépites afin de travailler efficacement avec notre code serait un énorme gaspillage de temps. Et ces secrets ne peuvent généralement pas être documentés par une «amélioration pour plus de clarté» sans commentaire.
LarsH

@LarsH Cela pourrait probablement être considéré comme l'une de ces "très rares exceptions" mentionnées dans mon commentaire. Je ne suis pas contre commenter lorsque cela ajoute de la valeur ; mais ce n'est pas la quantité de commentaires qui rend le code facile ou difficile à lire. Cela dit, avec une API, je serais plus enclin à documenter ces bizarreries ailleurs; dis, dans un wiki ou similaire. Peut-être aussi ajouter un lien vers la page correspondante à côté de chaque utilisation. Ainsi, vous n'avez pas besoin de rechercher un autre emplacement qui utilise cette fonctionnalité particulière de l'API lorsque le code ne fonctionne pas exactement comme vous le souhaitez lors de la première tentative.
un CVn

@ MichaelKjörling: d'accord en général. Que ces exceptions soient rares ou non dépend du domaine que vous programmez et des API que vous devez utiliser. Les liens / références sont utiles pour les notes qui s'appliquent généralement, pas seulement à la situation actuelle. Personne ne veut une thèse dans le code lui-même.
LarsH

-1

Ce programmeur effectue-t-il une maintenance du code? Sinon, il devrait: vérifier si vous avez un projet qui vous déplaît et lui confier la maintenance.

Ce sont généralement les projets mal documentés dans lesquels vous perdez des heures à essayer de comprendre ce qui se passe pour corriger ce qui aurait pu être facile à corriger. Si ce type d'expérience ne lui donne pas envie de mettre à jour, une documentation correcte et utile, rien ne le fera.


1
Cette approche est plus susceptible de faire cesser le programmeur plutôt que de le former à la bonne façon de faire les choses.
Martin Brown

-1

Dans l'un de mes projets antérieurs, il manquait des dizaines de commentaires (algorithme, résultats ou quelques JavaDoc de base), alors je viens de décider de lui faire 130 problèmes, une notification par courrier électronique à propos de chaque problème tous les quatre jours. Après 3 semaines, il avait 280 problèmes, puis il a décidé d'écrire des commentaires.


-1

Les commentaires ont un but, et un seul but:

Pourquoi ce code fait-il cette chose?

Si un commentaire n'explique pas pourquoi quelque chose est comme ça, alors il devrait être supprimé. Les commentaires inutiles qui encombrent le code sont moins qu'inutiles, ils sont activement nuisibles.

J'ai l'habitude de faire de mes commentaires la chose la plus évidente de mon IDE. Ils sont mis en évidence avec du texte blanc sur un fond vert. Le vraiment attirer votre attention.

En effet, le code explique ce que fait quelque chose et les commentaires expliquent pourquoi il le fait. Je ne saurais trop insister là-dessus.

Un bon exemple de commentaire:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Un mauvais exemple:

/* instantiate clsUser */

Si vous utilisez des commentaires en tant que "sections" de code: découpez votre méthode Mammoth en fonctions nommées plus petites et utiles, puis supprimez les commentaires.

Si vous dites ce que vous faites à la ligne suivante: Faites en sorte que le code soit auto-explicatif et supprimez le commentaire.

Si vous utilisez des commentaires comme messages d'avertissement: Assurez-vous de dire pourquoi.


-2

Pour compléter les réponses ici, je pourrais ajouter "Si vous voulez que ce soit bien fait, vous devez le faire vous-même."

Je ne veux pas dire devenir "commentateur de code en chef", je veux dire devenir un modèle en démontrant ce que vous voudriez que cet autre développeur fasse. Ils disent que montrer est plus efficace que dire . Si vous pouvez démontrer l'avantage de commentaires de qualité, ou même conseiller un autre développeur (dans la mesure où il le souhaite), vous obtiendrez peut-être plus de succès dans l'adoption de commentaires de code.

De même, à la maison, il y a des tâches ménagères que je ne tiens pas à faire. Cependant, ces mêmes tâches se trouvent être celles de ma femme… des tâches qui doivent être accomplies pour qu'elle soit heureuse. La même situation s'applique inversement. Je pense que vous devrez peut-être accepter que cet autre développeur a des priorités différentes de la vôtre et ne sera pas d'accord avec vous sur tout. La solution que ma femme et moi avons trouvée est que, pour les tâches ménagères, nous devons les faire nous-mêmes, même si cela signifie que nous devons faire un peu plus de travail par nous-mêmes.


1
Je dirais que montrer un code plus propre / refactoriser leur code pour qu'il soit plus lisible témoigne d'un changement plus important que l'insertion d'une foule de commentaires dans le code.
Makoto

Quelqu'un peut-il m'expliquer ce qu'ils n'aiment pas à propos de mon idée ...?
M. Dudley

-6

Simple: si l'employé ne fait pas de commentaires, dites-lui d'appuyer shift+alt+jsimultanément sur chaque commentaire pour chaque méthode, en même temps que le code. s'il vous plaît faire la révision du code pour éviter ces problèmes.


11
"Commentaire auto"? Donc, c’est deque viennent tous ces commentaires "incrémente de 1"? Quel IDE fait cela (afin que je puisse éviter les emplois où il est utilisé)?
un CVn

J'ai essayé de modifier cela en quelque chose de lisible, mais je ne suis pas sûr si le mot en premier devrait avoir une virgule avant ou après. La phrase fait-elle des commentaires en premier ou en premier dans chaque méthode ?
TRiG
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.