Comment convaincre les gens de commenter leur code

Quels sont les bons arguments pour convaincre les autres de commenter leur code?

Je remarque que beaucoup de programmeurs préfèrent la vitesse perçue de l’écriture du code sans commentaires, en laissant de la documentation pour eux-mêmes et pour les autres. Quand j’essaie de les convaincre, j’entends des choses à moitié cuites comme «le nom de la méthode / classe doit dire ce que ça fait», etc. Que leur diriez-vous de changer d’avis?

Si vous êtes contre les commentaires, veuillez simplement laisser des commentaires. Cela devrait être une ressource pour les personnes essayant de convaincre les gens de commenter le code, pas autrement. 🙂

Les autres questions connexes sont: Code de commentaire , commentez-vous votre code et comment aimeriez-vous vos commentaires ?

La meilleure façon de convaincre une personne est de la faire comprendre d’elle-même. Faites-les déboguer du code bien commenté. Cela leur montrera à quoi ressemblent les bons commentaires – les commentaires ne servent à rien, à moins qu’ils ne transmettent vraiment des informations pertinentes (ce qui est généralement le “pourquoi”, car le code décrit le “quoi”). Ils remarqueront comme c’est facile. Puis laissez-les revenir à leur ancien code. Ils remarqueront à quel point c’est difficile. Vous leur avez non seulement montré ce qu’il ne fallait pas faire, mais que faire (c’est plus important). Vous n’avez plus à faire. De plus, vous n’avez pas à essayer de les convaincre verbalement. Ils doivent simplement comprendre la nécessité de commenter le code à leur manière. C’est bien sûr, en supposant que le code à commenter ne soit pas explicite.

Seulement commenter le “pourquoi” et pas le “quoi”. Pour autant que je sois d’accord, la classe, la méthode ou le nom de la variable devrait indiquer clairement ce qu’elle fait et à quoi elle sert. Refactor où il ne le fait pas au lieu de le commenter.

Si vous adoptez cette approche, vous obtiendrez des commentaires et vous obtiendrez des commentaires utiles. Les programmeurs aiment expliquer pourquoi ils font quelque chose.

Montrez-leur leur propre code d’il y a 6 mois. S’ils ne peuvent pas comprendre et décrire exactement ce qu’ils font en 2 à 4 minutes, votre argument a probablement été formulé.

Mon avis:

Je ne le ferais pas Le nom de la méthode / classe doit indiquer ce qu’il fait. Si ce n’est pas le cas, la méthode ou la classe essaie de trop en faire ou elle est mal nommée.

Je suis fan de commenter pourquoi, pas quoi. Si ce n’est pas clair pourquoi le code utilise une approche par rapport à une autre, commentez-le. Si vous deviez append une variable inutilisée pour contourner un bug du compilateur, commentez pourquoi. Mais les commentaires comme “// Se connecter à la firebase database” sont des signes de mauvais code ou de mauvaises politiques. Une méthode nommée ConnectToDatabase () est bien meilleure. Et si elle contient “// Déterminer l’adresse IP du serveur de firebase database”, vous devriez peut-être utiliser une méthode nommée “DetermineDbServerIPAddress ()”.

La conception peut être documentée, mais les commentaires sont généralement un mauvais endroit pour ce niveau de documentation. Avec la connaissance de la conception, et quelques commentaires sur pourquoi, le quoi et comment devrait être évident. Si ce n’est pas le cas, plutôt que de les convaincre de commenter leur code, demandez-leur de l’améliorer.

Peut-être que c’est juste quelque chose qui doit être appris de l’expérience; en particulier, l’expérience de revenir à votre propre code après six mois et d’essayer de déterminer ce que vous pensiez (ou ce que vous faisiez) lorsque vous l’avez écrit. Cela m’a certainement convaincu que les commentaires n’étaient pas une si mauvaise idée.

Donnez-leur quelques ~ 500 lignes au minimum, un code spaghetti horrible et sans commentaire à refactoriser. Assurez-vous que les variables ne sont pas nommées logiquement. Whitespace optionnel.

Et voyez comme ils l’ aiment!

Trop dur, mais deux points en un coup.

  1. Ecrivez bien votre code.
  2. Commentez-le pour que vous et d’autres sachiez ce que cela signifie.

Je devrais insister sur le fait que ce code n’aurait pas dû provenir d’eux. Les commentaires sont vraiment utiles pour comprendre votre propre code, des mois plus tard, mais ils sont également essentiels pour comprendre des parties complexes du code d’ autres personnes . Ils doivent comprendre que quelqu’un d’autre pourrait avoir à comprendre ce qu’il fait.

Un dernier assembly: la qualité des commentaires est également très importante. Certains développeurs ont un ratio presque 2: 1 de code à commentaire dans leur travail, mais cela ne les rend pas de bons commentaires. Vous pouvez avoir étonnamment peu de commentaires dans votre code et toujours avoir beaucoup de sens.

  1. Explique ce que tu fais . Votre qualité de code devrait faire la plupart de ce travail pour vous.
  2. Plus important encore, expliquez pourquoi vous faites quelque chose ! J’ai vu tellement de code qui dit exactement ce que fait quelque chose, sans vraiment savoir pourquoi le développeur (malheureusement, la plupart du temps) pensait que c’était une bonne idée.

Rappelez-leur que la lecture du code ne peut que leur dire ce que le code fait , pas ce qu’il est censé faire.

Si vous ou les autres développeurs n’avez pas encore lu Code Complete (ou Code Complete 2 ), arrêtez ce que vous faites et lisez-le.

Une chose qui ressort est “Une fonction devrait faire juste une chose et le faire bien”. lorsqu’une telle fonction porte le nom d’une chose, il n’y a pas besoin de commentaire?

Les commentaires ont pour habitude de ne plus être synchronisés avec le code qu’ils sont censés décrire. Le résultat peut être pire que de ne pas avoir le commentaire original en premier lieu. Non seulement cela, mais les développeurs savent que les commentaires peuvent vieillir et ne peuvent pas être approuvés. Par conséquent, ils vont lire le code et discerner par eux-mêmes ce qu’il fait de toute façon! Cela annule en quelque sorte le sharepoint mettre les commentaires là-bas en premier lieu.

Ceci étant dit, il est possible que la même chose soit vraie pour un nom de fonction, mais cela a peut-être été bien nommé, mais de nouvelles opérations ont été ajoutées au temps supplémentaire.

Tous les commentaires semblent séparer les lignes de code qu’un développeur préfère être plus proches les unes des autres afin de pouvoir en voir plus par écran. Je connais ma propre réaction à un morceau de code avec beaucoup de commentaires que je dois comprendre. Supprimer tous les commentaires. Là maintenant je peux voir ce que le code est jusqu’à.

Au bout du compte, si vous passez du temps à bien faire les choses, votre temps est bien mieux consacré à la refactorisation du code pour vous assurer une description aussi raisonnable que possible, plutôt que de simplement écrire des commentaires. Un tel exercice est payant par d’autres moyens, comme l’identification de morceaux de code communs.

Cela vaut la peine de garder à l’esprit que beaucoup de bons développeurs préfèrent beaucoup écrire du C # clair, du Java propre, peu importe les langages humains beaucoup moins précis avec toutes les hypothèses et les ambiguïtés qu’ils ont. Certes, la plupart des gens de bon sens sauraient à quel point les détails sont suffisamment détaillés, mais les bons développeurs ne sont pas «la plupart des gens». C’est pourquoi nous nous retrouvons avec des commentaires comme \\adds a to b and store it in c (ok c’est trop extrême mais vous obtenez le point).

Les inviter à faire quelque chose qu’ils détestent faire et qui sont franchement pas très bons (même si vous êtes convaincu que c’est la bonne chose à faire) est simplement une bataille déjà perdue.

Je ne suis pas sarcastique à vous, mais vous devriez reformuler la question pour savoir comment convaincre les autres développeurs de travailler en équipe.

Sérieusement, certaines personnes supposent que vous pouvez lire dans leurs pensées.

Si vous faites partie d’une équipe agile, le code est détenu collectivement. Ainsi, lorsque vous voyez du code non commenté, maladroit ou difficile à lire, modifiez-le pour le comprendre. Si les gens se plaignent, dites-leur pourquoi et soyez franc. Que vous l’avez trouvé incompréhensible et que personne ne possède le code.

Notre stratégie consiste à procéder à des révisions systématiques du code et à rejeter les codes qui ne sont pas correctement documentés (par des commentaires, une dénomination et une organisation des fonctions appropriées, etc.). Si ce n’est pas clair pour l’examinateur, vous retournez sur le banc de travail, point final.

Je dirais “hier, j’ai dû lire une partie de votre code. J’ai été capable de le comprendre, mais moins de 5 lignes de commentaires bien choisis expliquant comment il a atteint ses objectives m’auraient permis d’en lire environ un. -alors, j’aurais pu m’inquiéter de comprendre un problème à la place, je ne suis pas stupide et tu n’es pas plus intelligent parce que tu peux écrire des choses difficiles à comprendre. documentation lisible + ensembles de codes alors vous êtes moins développeur. ”

Il y a longtemps que je me suis fait pénétrer: si vous écrivez quelque chose et que quelqu’un de raisonnable ne peut pas le comprendre, alors c’est votre faute, pas sa faute. Cela s’applique à l’écriture en langage naturel et s’applique à l’écriture dans les langages de programmation.

Il y a eu des discussions similaires sur les commentaires. Voici celle sur les règles que les gens suivent lors du commentaire de code: Quelles sont vos «règles ssortingctes» concernant le commentaire de votre code? . Certaines des réponses ont également de très bonnes raisons de vouloir commenter votre code.

Faites preuve de sagesse dans votre désir de commentaires et ils seront plus enclins à écouter.

Moins est plus.

Mettre l’accent sur la qualité plutôt que la quantité.

Dans mon équipe, il y avait une pression pour tout commenter dans certaines API. Certains développeurs ont commencé à utiliser un outil qui générerait automatiquement des commentaires en examinant les noms et les signatures des méthodes.

Par exemple:

 ///  /// Gets the Person. ///  ///  /// A Person ///  public Person GetPerson() { } 

Pouvez-vous penser à un plus grand gaspillage de biens immobiliers? Pouvez-vous penser à un gaspillage plus important des cycles cérébraux que la lecture de commentaires ne fournissant aucune nouvelle information?

Si la signature de la méthode le prouve, ne le dites pas! Si je peux le comprendre en quelques secondes, ne le mettez pas dans un commentaire. Comme d’autres l’ont dit, dites-moi pourquoi vous avez choisi de le faire de cette façon, et non ce que vous avez fait. Ecrivez votre code pour qu’il soit évident.

Mener par l’exemple. Les développeurs sont facilement influencés lorsqu’ils voient The Right Thing, alors voir des pratiques solides en action peut les encourager à faire de même. De plus, vous pouvez encourager votre groupe à adopter des mesures de code qui traitent de la maintenabilité du code et des commentaires. Par exemple, l’parsing de code produira un bogue pour les méthodes sans documentation récapitulative.

Les normes de codage actuelles à mon lieu de travail actuel consistent à commenter chaque fonction. Des règles comme celles-ci sont nuisibles et ne devraient jamais être en place. Il y a des situations (et certaines d’entre elles sont courantes) où l’ajout de commentaires supprime la lisibilité.

 class User { getUserName() { /* code here */ } } 

Quel est l’intérêt d’append un en-tête de fonction à la partie de code ci-dessus? Qu’est-ce que vous allez dire d’autre, les “récupère le nom d’utilisateur”. Tous les codes ne doivent pas être commentés. Ma règle de base est la suivante: ignorez les commentaires si vous n’ajoutez aucune information utile que la signature de la fonction ne contient pas.

Les commentaires doivent être complets, écrits au niveau de l’intention (pourquoi pas comment) et rares.

Lorsque j’écris du code, j’ai tendance à faire des commentaires assez lourds. Ensuite, je retourne et j’essaie de supprimer autant de commentaires que possible, sans nuire à la compréhensibilité du code. > 80% du temps, c’est aussi simple que d’extraire une méthode bien nommée, cela se traduit généralement par un commentaire qui ne fait que dupliquer les informations contenues dans le code lui-même. Au-delà de cela, s’il y a une section de code qui “nécessite” un commentaire, je cherche des moyens de la simplifier ou de la rendre plus claire.

Le code doit être auto-documenté, et avec les bonnes techniques, vous pouvez obtenir 95% de la facilité assez facilement. En général, je considère que c’est un échec s’il rest des commentaires sur le code que j’inscris.

Cela dépend de la puissance que vous avez …

J’ai trouvé un moyen très efficace d’en faire une partie fixe des revues de code basées sur les pairs – des points pour les commentaires. Si on faisait remarquer que le code avait été mal commenté, je le ferais remarquer par le développeur à ma satisfaction, ce qui signifiait qu’il devait décrire suffisamment le code pour que je le comprenne en l’imprimant et en le lisant. Et je le ferais aussi.

Remarquablement, cela a été populaire auprès des développeurs, même si cela semble dickensien. Deux choses se sont passées. Tout d’abord, les gens ont commencé à commenter leur code. Deuxièmement, le code mal commenté est devenu un signe que le développeur n’a pas bien compris ce qu’il avait écrit (sinon, ils l’auraient décrit).

Le seul inconvénient était que les commentaires devaient être conservés avec le code lors de sa révision pour les corrections de bogues, etc. Cela était presque impossible à appliquer dans une véritable boutique de développement, mais une fois que les bonnes pratiques étaient bien enracinées, .

BTW je préfère les commentaires dans le code lui-même plutôt qu’un roman Dostoevsky comme une chaîne de doc. Le premier est une aide utile pour les programmeurs suivants. Ce dernier est juste un long morceau de texte obsolète qui remplit les documents et induit tout le monde en erreur.

Demandez-leur d’utiliser une API peu familière, mais faites la programmation sur une machine non connectée à Internet (si vous pouvez les trouver aujourd’hui) afin qu’ils n’aient pas access à la documentation de l’API. C’est effectivement ce qu’ils obligent les autres développeurs à faire s’ils essaient d’utiliser le code des non-documenteurs!

Vous devez également différencier deux commentaires différents ici:

  • Commentaires sur l’API (javadoc ou autre type de documentation similaire): vous pouvez leur demander d’ utiliser leur propre code dans un scénario limite (conditions aux limites telles que des objects nuls ou des chaînes vides ou …) et voir s’ils parviennent effectivement à se rappeler leurs propres fonctions dans ces cas
    (C’est pourquoi je suis pour un javadoc complet incluant la valeur limite )

  • Commentaires internes (dans le code source): vous pouvez leur demander d’expliquer les fonctions qu’ils ont codées, choisir une fonction avec un niveau de complexité cyclomatique très élevé et les voir se débattre avec les différents workflows de code et les twigs de décision;)

Eh bien, il y a toujours le “si vous ne commentez pas votre code, nous trouverons quelqu’un d’autre qui commentera leur approche”.

Plus doucement, dites-leur qu’ils laissent tomber l’équipe s’ils ne documentent pas et ne commentent pas ce qu’ils font. Le code n’appartient pas à l’individu, sauf s’il s’agit de loups solitaires complets. Il appartient à l’équipe, au groupe, qu’il s’agisse d’une entreprise ou d’une communauté.

“Writing Code” = “Ecriture de la séquence des commandes dans une langue spéciale” + “Ecriture des commentaires”

Il sera évident de commenter le code tout en l’écrivant ! Avez-vous déjà commenté un code qui a déjà 3 ou 4 mois? (Bien sûr que vous l’avez, et c’était tout sauf amusant!)

Si votre projet est déjà bien documenté, les programmeurs qui ajoutent du nouveau code peuvent être motivés pour écrire des commentaires de la même manière.

@ James Curran Je suis 100% d’accord! Je peux lire votre code et comprendre ce que vous avez demandé au compilateur de faire; mais cela ne signifie pas que c’était votre intention de faire le compilateur faire ça. Je sais que je ne suis pas un programmeur assez arrogant pour croire que chaque fois que j’écris du code, il fait exactement ce que j’essayais de faire. De plus, je trouve souvent que cela m’aide à attraper des erreurs de logique stupides dans mon code en le parcourant après l’avoir écrit et en essayant d’expliquer ce que je voulais que le code fasse.

Une idée est de souligner qu’il faut moins d’une minute pour écrire une ou deux phrases par classe et moins d’une demi-minute pour écrire une phrase par méthode.

Dites-leur de documenter leurs fonctions et interfaces avec les communications Javadoc, puis d’exécuter le code via Doxygen pour générer une documentation HTML attrayante pour leur code. Le facteur de fraîcheur peut parfois être un bon facteur de motivation.

J’utilise une technique subtile:

J’ai défini le niveau des avertissements dans le projet à signaler en tant qu’erreurs. Et notre serveur d’continuous integration construit la solution complète avec la documentation XML à chaque démarrage.

Si les développeurs n’écrivent pas les commentaires, la construction échoue! Et après cela, ils doivent écrire les commentaires, alors après un certain temps, ils s’y sont habitués.

Ce n’est pas agressif en termes de pression, mais je trouve que c’est une façon agréable de corriger leur comportement.

Si les développeurs doivent prendre part à des revues de code et sont exposés à de bons commentaires, ils devraient être en mesure d’en savoir plus. S’ils ne considèrent pas la pratique comme utile, ils devraient recevoir des commentaires de leurs pairs.

À défaut (en supposant que vous êtes le superviseur / gestionnaire), faites-en une partie de leur évaluation du rendement. Si vous pouvez le mesurer, vous pouvez évaluer en fonction de celui-ci.

Assurez-vous que vous marquez un commentaire REVIEWED, car les développeurs passifs-agressifs documenteront chaque dernière déclaration en tant que FU peu subtile.

Je suis fermement convaincu de ce que j’appelle la règle de Headrick , nommée d’après un de mes collègues qui a découvert qu’une bonne façon de motiver quelqu’un à faire quelque chose est de lui faire mal de ne pas le faire.

Dans votre cas, demander à vos développeurs qui ne commentent pas de passer une heure ou deux à expliquer leur code, peut-être à un public “lent”, peut-être pendant leur heure de déjeuner “pour éviter le dérapage du projet” ira loin. Les gens intelligents – même les plus obstinés – apprennent vite!

À mon avis (et je parle de la programmation .Net ici), si vous devez mettre un commentaire, vous avez échoué à rendre le code lisible. La réponse est généralement refactor!

Cependant, si vous pensez devoir mettre un commentaire, il devrait toujours s’agir d’un type de commentaire “pourquoi” et non d’un commentaire expliquant ce que fait le code.

En écrivant ce que fera une méthode / classe avant de la coder, cela aide beaucoup à bien faire les choses – et vous l’avez commenté.

N’employez que de bons ingénieurs qui s’assurent que leur code énonce implicitement l’intention (en utilisant des commentaires et autres). Quiconque veut un emploi devra le faire correctement. Dur, mais juste, à mon humble avis.