Comment convaincre les gens de commenter leur code [fermé]

https://stackoverflow.com/questions/159597

03-07-2019
|

Question

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

Je remarque que de nombreux programmeurs privilégient la vitesse perçue d’écriture de code sans commentaires au lieu de laisser de la documentation pour eux-mêmes et d’autres. Quand j'essaie de les convaincre, j'entends des choses à moitié cuites comme "le nom de la méthode / classe devrait dire ce qu'il fait". etc. Que leur diriez-vous de changer d'avis?

Si vous ne souhaitez pas commenter, vous pouvez 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 les suivantes: code de commentaire , Commentez-vous votre code et Comment souhaitez-vous recevoir vos commentaires .

La solution

Le meilleur moyen de convaincre une personne est de lui faire réaliser cela par lui-même. Faites-leur déboguer du code bien commenté. Cela leur montrera à quoi ressemble un bon commentaire - les commentaires ne sont d'aucune utilité à moins qu'ils ne véhiculent réellement des informations pertinentes (ce qui est généralement le "pourquoi", car le code décrit le "quoi"). Ils remarqueront à quel point c'est facile. Puis laissez-les revenir à certains de leurs anciens codes. Ils remarqueront à quel point c'est difficile. Vous leur avez non seulement montré ce qu'il ne fallait pas faire, mais ce qu'il fallait faire (c'est plus important). Tu n'as 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. Ceci est bien sûr supposé que le code à commenter n’est pas explicite.

Autres conseils

Ne commentez que le " pourquoi " et non le "quoi". Dans la mesure où je suis d’accord, le nom de la classe ou de la méthode ou le nom de la variable doit clairement indiquer ce qu’elle fait et à quoi elle sert. Refactoriser là où ce n'est pas le cas au lieu de le commenter.

Si vous adoptez cette approche, vous obtiendrez des commentaires et 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 comprennent pas et ne décrivent pas exactement ce que cela fait en 2 à 4 minutes, votre remarque a probablement été faite.

Mon avis:

Je ne voudrais pas. Le nom de la méthode / classe devrait dire ce qu'il fait. Si ce n'est pas le cas, la méthode ou la classe essaie de faire trop, ou le nom est mal nommé.

Je suis fan de commenter pourquoi, pas quoi. Si la raison pour laquelle le code utilise une approche plutôt qu'une autre n'est pas claire, commentez-la. Si vous deviez ajouter une variable de hack inutilisée pour contourner un bogue du compilateur, commentez pourquoi. Mais des commentaires comme "// Connexion à la base de données" sont des signes de mauvais code ou de mauvaises politiques. Une méthode nommée ConnectToDatabase () est bien meilleure. Et s’il a " // Déterminer l’IP du serveur de base de données " peut-être que cela devrait être extrait d’une méthode nommée "DetermineDbServerIPAddress ()".

La conception peut être documentée, mais les commentaires sont généralement un endroit médiocre pour ce niveau de documentation. Avec la connaissance de la conception, et quelques commentaires sur pourquoi, 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; Plus précisément, revenez à votre propre code après six mois et essayez de comprendre ce que vous pensiez (ou ce que vous étiez en train de penser) au moment de l’écrire. Cela m'a certainement convaincu que les commentaires n'étaient pas une si mauvaise idée.

Donnez-leur du code de spaghetti horrible et non commenté (environ 500 lignes, minimum) au refactor. Assurez-vous que les variables ne sont pas nommées logiquement. Espace blanc facultatif.

Et voyez comme ils l'apprécient!

Trop dur, mais il obtient deux points d'un coup.

Écrivez bien votre code.
Commentez-le pour que et les autres sachiez ce que cela signifie.

Je tiens à souligner que ce code n'aurait pas dû provenir d'eux. Les commentaires sont pour comprendre votre propre code, des mois plus tard, mais ils sont également indispensables pour comprendre les parties complexes du code des autres . Ils doivent comprendre que quelqu'un d'autre devra peut-être comprendre ce qu'ils font.

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

Expliquez ce que vous faites . La qualité de votre code devrait faire la plupart de ces travaux pour vous cependant.

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 moi) pensait que c'était une bonne idée.

Rappelez-leur que la lecture du code ne peut leur dire que ce que le code fait , et non ce qu'il est supposé faire.

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

Une chose qui se démarque est "Une fonction ne doit faire qu’une chose et la faire bien". quand une telle fonction est nommée d'après la seule chose, elle fait bien quoi de plus besoin de commenter?

Les commentaires ont l’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 qu'on ne peut pas leur faire confiance. Par conséquent, ils vont lire le code et discerner par eux-mêmes ce qu'il fait réellement de toute façon! Ce genre annule le point de mettre les commentaires là-bas en premier lieu.

Cela dit, il peut en être de même pour un nom de fonction. Le nom de la fonction a peut-être bien été nommé, mais de nouvelles opérations supplémentaires ont été ajoutées qui ne sont pas mentionnées dans le nom.

Tous les commentaires semblent séparer les lignes de code qu'un développeur préférerait rapprocher pour 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à, je peux voir ce que le code est jusqu'à.

À la fin de la journée, si vous allez passer du temps à régler correctement votre temps , vous ferez bien mieux de remanier le code pour qu'il soit suffisamment descriptif et auto-descriptif au lieu de simplement écrire commentaires. Un tel exercice rapporte d’autres manières, comme l’identification de morceaux de code courants.

Il est bon de noter que beaucoup de bons développeurs préfèrent écrire des langages C # et Java précis, bien précis, que les langages humains beaucoup moins précis, avec toutes les hypothèses et ambiguïtés qu’ils ont. Certes, la plupart des gens doués de bon sens sauraient combien de 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 tels que \\ ajoute a à b et le stocke dans c (ok, c’est trop extrême, mais vous comprenez le point).

Leur demander de faire quelque chose qu’ils détestent et qu’ils ne sont franchement pas très doués (même si vous êtes convaincu que c’est la bonne chose à faire) est tout simplement une bataille déjà perdue.

Je ne suis pas sarcastique envers vous, mais vous devriez reformuler la question pour qu'elle soit Comment convaincre les autres développeurs de travailler en équipe?

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

Si vous faites partie d'une équipe agile, le code est une propriété collective. Par conséquent, lorsque vous voyez du code non commenté, maladroit ou difficile à lire, continuez et changez-le (refactor) 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 le code qui n'est pas correctement documenté (par le biais de commentaires, d'un nom de fonction et d'une organisation appropriés, etc.). Si ce n'est pas clair pour le relecteur, vous retournez au banc de travail, un point c'est tout.

Je dirais "hier, je devais lire une partie de votre code. Je pouvais le comprendre, mais moins de 5 lignes de commentaire bien choisies expliquant comment il avait atteint ses objectifs m'auraient permis de le lire dans environ un dixième du temps. J'aurais alors pu m'inquiéter de comprendre problème à la place. Je ne suis pas stupide et vous n'êtes pas plus intelligent parce que vous pouvez écrire des choses difficiles à comprendre. Au contraire, si vous ne pouvez pas produire de documentation lisible + des ensembles de code, vous êtes moins un développeur. "

Je me suis fait exploser ceci il y a longtemps: si vous écrivez quelque chose et que quelqu'un qui a une capacité raisonnable ne peut pas le comprendre, alors c'est votre faute, pas la sienne. Ceci s’applique à l’écriture en langage naturel et à l’écriture en langage de programmation.

Des discussions similaires ont eu lieu à propos des commentaires. Voici celle sur les règles suivies par les utilisateurs pour commenter le code: Quelles sont vos "règles strictes"? commenter votre code? . Certaines réponses ont également de très bonnes raisons pour lesquelles vous souhaitez commenter votre code.

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

Moins, c'est plus.

Mettez l'accent sur la qualité plutôt que sur 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 consultant les noms de méthodes et les signatures.

Par exemple:

/// <summary> /// Gets the Person. /// </summary> /// <returns> /// A Person /// </returns> public Person GetPerson() { }

Pouvez-vous penser à un plus grand gaspillage d’immobilier d’écran? Pouvez-vous penser à un plus grand gaspillage de cycles cérébraux que de lire des commentaires qui ne fournissent aucune information nouvelle?

Si cela ressort clairement de la signature de la méthode, 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 ainsi, et non ce que vous avez fait. Ecrivez votre code pour qu'il devienne évident ce qu'il fait.

Donner l'exemple. Les développeurs sont facilement influencés quand ils voient The Right Thing. Par conséquent, voir des pratiques solides en action peut les encourager à faire de même. De plus, vous pouvez encourager votre groupe à adopter des métriques de code qui traitent de la maintenabilité du code et des commentaires. Par exemple, Code Analysis générera un bogue pour les méthodes sans documentation récapitulative.

Les normes de codage actuelles sur mon lieu de travail actuel consistent à commenter chaque fonction. Les règles masquées comme celle-ci sont nuisibles et ne devraient jamais être en place. Il existe des situations (et certaines communes) dans lesquelles l'ajout de commentaires supprime la lisibilité.

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

Quel est l’intérêt d’ajouter un en-tête de fonction au code ci-dessus? Qu'allez-vous dire d'autre? Besdies "obtient le nom d'utilisateur". Tout le code n'a pas besoin d'être commenté. Ma règle empirique est la suivante: ignore les commentaires si vous n’ajoutez aucune information utile, contrairement à la signature de la fonction.

Les commentaires doivent être approfondis, rédigés au niveau de l'intention (pourquoi pas comment) et rares.

Lors de la rédaction de code, j’ai tendance à faire des commentaires raisonnablement lourds. Ensuite, je relis et essaie de supprimer autant de commentaires que possible, sans diminuer la compréhensibilité du code. > 80% du temps, c’est aussi simple que d’extraire une méthode bien nommée, il en résulte généralement un commentaire qui ne fait que dupliquer les informations contenues dans le code lui-même. Au-delà, s’il existe une section de code qui a besoin de " un commentaire que je cherche des moyens de le simplifier ou de le rendre plus clair.

Le code doit être auto-documenté, et avec les bonnes techniques . peut obtenir 95% du chemin là assez facilement. En général, j’estime qu’il ya échec s’il reste des commentaires sur le code que j’ai archivé.

Cela dépend de votre puissance ...

J'ai trouvé un moyen très efficace d'en faire une partie intégrante des révisions de code par des pairs - des points pour les commentaires. Si vous remarquiez que le code a été mal commenté, je ferais en sorte que le développeur le commente à ma satisfaction, ce qui signifie qu’ils doivent décrire suffisamment le code pour que je puisse le comprendre en l’imprimant et en le lisant. Et je le ferais aussi.

Remarquablement, cela était 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, un code mal commenté est devenu un signe que le développeur ne comprend pas très bien ce qu'il a écrit (sinon, il l'aurait décrit).

Le seul inconvénient, c’est que les commentaires doivent être conservés avec le code lorsqu’il a été révisé pour la résolution de bugs, etc. Cela était presque impossible à appliquer dans un véritable atelier de développement, mais une fois qu’il avait suffisamment de bonnes pratiques, il s’agissait de le trier est arrivé naturellement.

En passant, je préfère les commentaires dans le code lui-même plutôt qu'un roman de Dostoïevski en tant que chaîne de documentation. Le premier est une aide utile pour les programmeurs ultérieurs. Ce dernier n’est qu’un long texte périmé qui remplit les documents et trompe tout le monde.

Demandez-leur d'utiliser une API inconnue, mais effectuez la programmation sur un ordinateur non connecté à Internet (si vous pouvez les trouver ces jours-ci), de sorte qu'ils n'aient aucun accès à la documentation de l'API. C’est effectivement ce qu’ils forcent les autres développeurs à faire s’ils essaient d’utiliser le code des non-documenteurs!

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

Commentaires sur l'API (documentation javadoc ou autre type de documentation similaire): vous pouvez les demander à utilisent leur propre code dans un scénario limite (conditions aux limites telles que des objets null ou des chaînes vides ou ...) et voir s'ils parviennent réellement à se souvenir de leurs propres fonctions dans ce 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 toute fonction qu'ils ont codée. Il vous suffit de choisir une fonction avec un vraiment niveau de complexité cyclomatique élevé , et les voir se débattre autour des différents flux de travail de code et de branchement 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 le leur". approche.

Plus doucement, dites-leur qu'ils abandonnent cruellement l'équipe s'ils ne documentent pas et ne commentent pas ce qu'ils font. Le code n'appartient pas à l'individu, à moins qu'il s'agisse de loups solitaires. Cela appartient à l'équipe, au groupe, qu'il s'agisse d'une entreprise ou d'une communauté.

" code d'écriture " = "Rédaction d’une séquence de commandes dans un langage spécial" + "Rédaction de commentaires"

Il va de soi que vous pouvez commenter un 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 avez, et c'était tout sauf amusant!)

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

@James Curran I 100% d'accord! Je peux lire votre code et comprendre ce que vous avez dit au compilateur de faire; mais cela ne signifie pas que votre intention était de faire en sorte que le compilateur le fasse. 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 le faire faire. De plus, je trouve souvent que cela m'aide à détecter les erreurs de logique stupides dans mon code en parcourant une fois que je l'ai é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 des commentaires Javadoc, puis d'exécuter le code via Doxygen pour générer une documentation HTML de qualité pour leur code. Le facteur 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 comme des erreurs. Et notre serveur d'intégration continue construit l'ensemble de la solution ainsi que la documentation XML à chaque enregistrement.

Si les développeurs n'écrivent pas les commentaires, la construction échoue! Et après cela, ils doivent écrire les commentaires, donc au bout d’un moment, ils s’y sont habitués.

Ce n’est pas agressif en termes de pression, mais je trouve que c’est un bon moyen de corriger leur comportement.

Si les développeurs doivent prendre part à la révision du code et sont exposés à de bons commentaires, ils devraient pouvoir en obtenir la moindre idée. S'ils ne jugent pas la pratique utile, ils devraient alors obtenir des commentaires de leurs pairs examinateurs.

Si vous échouez (si vous êtes le superviseur ou le responsable), intégrez-le à l'évaluation de leurs performances. Si vous pouvez le mesurer, vous pouvez évaluer sur cette base.

Assurez-vous qu'il s'agit d'un commentaire RÉVISÉ sur lequel vous marquez des points, car les développeurs passifs-agressifs documenteront chaque dernière déclaration en tant que FU pas si subtile.

Je suis devenu un fervent partisan de ce que j'appelle la règle de Headrick , en référence à un de mes collègues qui a découvert qu'un bon moyen de motiver quelqu'un à faire quelque chose est de le rendre douloureux pour lui < em> pas pour le faire.

Dans votre cas, demandez à vos développeurs qui ne commentent pas de passer une heure ou deux à expliquer leur code, peut-être à un "lent". public, peut-être à l’heure du déjeuner "pour éviter tout dérapage du projet" ira un long chemin. Les personnes intelligentes, même les plus obstinées, apprennent vite!

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

Cependant, si vous estimez que vous devez mettre un commentaire, il devrait toujours s'agir d'un "pourquoi" et d'un "pourquoi". type de commentaire et non un commentaire expliquant le comportement du code.

Ecrire ce qu'une méthode / classe va faire avant de la coder aide beaucoup à bien faire les choses - et vous l'avez commenté.

N'utilisez que de bons ingénieurs qui s'assurent que leur code énonce l'intention de manière implicite (en utilisant des commentaires et autres). Quiconque veut un travail devra le faire correctement. Dur, mais juste, à mon humble avis.

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow