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

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?

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.

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.

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)

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.

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.

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.

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).

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.

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!

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.

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?

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.

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.

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.

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

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.

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.

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à.

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.

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.

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.

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.

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.