Les commentaires dépassés sont-ils un mythe urbain?


38

Je vois constamment des gens prétendre que "les commentaires ont tendance à devenir obsolètes". Le problème, c’est que j’ai peut-être vu deux ou trois commentaires obsolètes toute ma carrière. Les informations obsolètes contenues dans des documents distincts sont fréquentes, mais selon mon expérience, les commentaires obsolètes dans le code lui-même sont extrêmement rares.

Ai-je juste eu de la chance avec qui je travaille? Certaines industries sont-elles plus exposées à ce problème que d'autres? Avez-vous des exemples spécifiques de commentaires obsolètes que vous avez vus récemment? Ou les commentaires obsolètes sont-ils davantage un problème théorique qu'un problème réel?


30
D'accord. Le code obsolète fait l'objet d'un commentaire. C'est quelque chose que je vois souvent - et que j'aimerais moins.
pyvi

8
Je vois plus le manque de commentaires que ce soit. Combinée à de mauvaises conventions de dénomination, c’est une boule de plaisir à essayer de lire certaines des choses avec lesquelles je travaille.
P.Brian.Mackey le

2
J'ai vu beaucoup de commentaires obsolètes, dont certains étaient tout simplement trompeurs. Certainement pas un mythe, mais est surtout valable pour des projets maintenus par de nombreuses personnes et / ou pendant longtemps, amplifiés par la complexité. Cependant, j'ai appris à faire confiance au code, pas aux commentaires (je ne les lis presque jamais s'ils dépassent plus d'une ligne).
MaR

J'ai surtout travaillé avec un très ancien code hérité tout au long de ma carrière. Il y a eu environ une douzaine de fois où j'ai eu de graves problèmes liés à des commentaires obsolètes dans un code Fortan77 étrange datant de 30 ans, mais il s'agissait d'un pourcentage presque nul du code pour lequel les commentaires étaient suffisants. Je suis donc d’accord pour dire que l’ampleur d’un problème a dû être exagérée.
SK-logic

Juste ma chance, j'en ai vu pas mal dans l'année depuis que j'ai posté ceci. J'imagine que j'avais inconsciemment appris à ne pas leur faire confiance, puis à les corriger et à passer à autre chose, sans trop y penser.
Karl Bielefeldt

Réponses:


33

Constamment

Je ne peux vraiment pas croire que je suis la seule à nager dans des commentaires désuets et trompeurs. Au hasard, cela aide à comprendre:

Cela dépend probablement de l'âge du code. Le facteur suivant serait le roulement du personnel.

Je fais de la R & D et de la maintenance à parts égales. La R & D est un nouveau code, généralement un peu hors des sentiers battus. Bon nombre de mes collègues croient qu'il faut inclure beaucoup d'explications commentées pour essayer quelque chose pour lequel il n'y a pas de bibliothèque. Étant donné que le ratio commentaire sur code est supérieur à la normale, les possibilités de désynchronisation sont encore plus nombreuses.

Le code de maintenance ... Je suis un responsable actif sur un système de plus de 10 ans et un autre de plus de 5 ans. Le code et les commentaires datant de 10 ans sont atroces, comme on peut s'y attendre. En 10 ans, vous avez beaucoup de mains dans le code et personne n’a aucune idée de la façon dont tout cela fonctionne. Le code de 5 ans et les commentaires sont plutôt bons parce que le taux de rotation de l'équipe a été plutôt faible.

Je travaille presque tous les services, même nos produits sont hautement personnalisés pour un client particulier.

Exemples spécifiques:

  • Commentaires décrivant l'amélioration des performances pour une méthodologie particulière, par exemple pour éviter une copie en mémoire. Un gros problème quand une machine haut de gamme dans un Pentium 2 avec des Mo de RAM, mais à peine un problème pour le moment.

  • TODOs

  • Blocs de code copié-collé incluant des commentaires. Le commentaire a peut-être eu un sens à son emplacement d'origine, mais n'a guère de sens ici

  • Les blocs de commentaires se trouvant en haut du code commenté (qui sait depuis combien d'années cela existe).

Dans tous ces domaines, on observe une tendance à ne pas simplement maintenir les commentaires et le code au même niveau que le logiciel. Les IDE et les habitudes de base des développeurs n’aident en rien, mon œil a été entraîné à les dépasser rapidement. Je pense que les commentaires obsolètes sont relativement peu coûteux à éviter dans les projets en plein champ et actifs. Si vous pouvez garder le rapport code / commentaire élevé, ce n'est pas grave de les garder à jour. Il est un peu plus difficile de justifier la recherche de ces éléments lorsque le budget fixé pour x heures est corrigé pour corriger un bogue sur un système de production.


Donc, en gros, vous dites que vous ignorez tout simplement les commentaires parce que c'est déjà trop gros, et que cela ne fait qu'aggraver la situation. Pas vraiment surprenant.
Steven Jeuris le

5
@Steven - Moi personnellement, non. Je suis un fervent partisan de l'amélioration progressive. J'ai vu des codes de code complètement indéchiffrable devenir assez décents avec suffisamment d'effort progressif. Mais ignorer est certainement la norme dans mon expérience. C'est très compréhensible lorsque vous rencontrez plusieurs 10000 classes de lignes entrelacées avec des semaines de problèmes à cataloguer, les commentaires obsolètes ayant tendance à tomber au bas de la liste des priorités.
Steve Jackson le

1
@Steve: Dans votre cas, je créerais simplement un script qui enlèverait alors tous les commentaires et commencerais à commenter à partir de zéro si nécessaire. :)
Steven Jeuris le

1
La base de code principale sur laquelle je travaillais était au moins la moitié des commentaires et rarement commentée. Les commentaires obsolètes étaient une réalité, les commentaires corrects étaient extrêmement rares et je ne commencerai même pas à commenter sur la documentation !!! vue ... Après ce travail, j'ai appris que moins c'est bien, si votre code a besoin de commentaires, il a probablement besoin d'un refactor pour rendre les choses plus évidentes ...
Newtopian

4
J'ai vu de terribles exemples de Blocks of copy-pasted code including comments. Comment may have made sense in its original location, but hardly makes sense here. Les commentaires au niveau de la classe parlent d'une classe différente, par exemple.
Peter Taylor

18

"Les commentaires ont tendance à devenir obsolètes."

J'ai vu cela se produire assez souvent pour savoir que cela peut être un problème.

Le problème, c’est que j’ai peut-être vu deux ou trois commentaires obsolètes toute ma carrière.

Je pense qu'il devrait être parfaitement possible de travailler dans un environnement où tout le monde prend suffisamment en compte les commentaires et les maintient. Il suffit d'un petit effort supplémentaire pour examiner les commentaires proches du code que vous modifiez et les mettre à jour le cas échéant. Si les commentaires sont si éloignés que vous ne les remarquez pas tout de suite, c’était quand même de mauvais commentaires et n’auraient pas dû être ajoutés en premier lieu (ou du moins pas là).

De plus, généralement, avec l'affirmation que les commentaires ont tendance à devenir obsolètes, il en découle que cela réduit la lisibilité et déroute les gens. C'est quelque chose que je n'ai pas encore expérimenté. Chaque fois que je rencontre un commentaire obsolète, je vois clairement ce qui a changé et le met à jour en conséquence afin de représenter le code le plus récent, bien qu'avec un effort supplémentaire.


Une étude récente de Roehm et al. 2012 observe ce qui suit:

21 participants [sur 28] ont déclaré qu'ils tiraient leurs informations principales du code source et des commentaires en ligne, tandis que quatre seulement ont déclaré que la documentation était leur principale source d'informations.

Cela va dans le sens de votre suspicion selon laquelle les commentaires dans le code lui-même sont toujours considérés comme très utiles. Cela indique qu’il faut tracer une ligne de démarcation nette entre la documentation obsolète et les commentaires obsolètes .

Roehm, T., R. Tiarks, R. Koschke et W. Maalej (juin 2012). Comment les développeurs professionnels comprennent-ils les logiciels?. Dans Actes de la Conférence internationale sur le génie logiciel de 2012 (p. 255-265). IEEE Press.


Devenu meilleur, j’ai constaté que j’ai besoin de moins de commentaires pour comprendre ce que fait le code typique du code plug n chug.
Paul Nathan

3
Nathan @ Paul, les commentaires ne doit jamais décrire ce que le code fait - le code décrit que mieux. Les commentaires sont là pour expliquer pourquoi le code fait ce qu'il fait.
SK-logic

2
@ SK-logic: Bien que je comprenne l'argument, je le crois trop large. Les commentaires d'une fonction (ou d'un paragraphe / bloc de code) peuvent clarifier beaucoup plus (et plus rapidement) le rôle de la fonction que son nom. Ceci est particulièrement nécessaire pour les fonctions publiques. Aussi facile que le code puisse être lu, la lecture d'une explication à deux lignes du code à dix lignes est encore plus rapide. Imaginez que vous travailliez avec votre API préférée qui ne contient aucune documentation "quoi" . Vous seriez beaucoup moins sûr de sa fonctionnalité.
Steven Jeuris

Eh oui, je n'ai pas inclus de documentation (par exemple, Javadoc) - elle est trop structurée pour s'appeler simplement " commentaires ".
SK-logic

17

Les commentaires périmés sont une odeur de travail. C'est comme avoir des tests unitaires obsolètes ou négligés - cela montre que les bons processus qui étaient autrefois actifs dans le magasin sont en train de dégénérer en codage cow-boy. La "culture d'ingénierie" appropriée consistant à prendre le temps de faire les choses correctement s'est effondrée. Le projet / l'entreprise est susceptible de contracter une dette technique.

En bref, oui, vous avez eu de la chance. Si vous avez une série de magasins raisonnablement bien gérés jusqu'à présent dans votre carrière, il est tout à fait possible de ne pas en voir autant. Mais dans les magasins plus typiques, moins bien gérés, cela se fait parallèlement au reste du chaos.


"Les commentaires périmés sont une odeur d'emploi." Très bien mis! De même, un code auto-documenté, mais sans commentaires, n'est pas la solution, mais un "hack" paresseux.
Steven Jeuris

10

Les commentaires sont comme des tests, ils sont très bons quand ils sont à jour, mais peuvent rendre encore plus difficile la compréhension du code s'il n'y en a pas.

Si vous n'avez jamais vu de commentaires obsolètes, vous avez eu beaucoup de chance.

La plupart des bases de code sur lesquelles j'ai travaillé étaient pleines de commentaires obsolètes et, généralement, je les ignore complètement, car ils sont source de confusion plutôt que d'aide.


Puis-je demander dans quelles industries vous avez travaillé? Je me demande si cela est plus courant chez certains que chez d'autres.
Karl Bielefeldt le

J'ai travaillé dans 3 pays différents en Europe, principalement en tant que consultant pour une grande et une petite entreprise. Dernièrement dans une maison de développement SaaS.
Kim.Net


10

Les commentaires obsolètes apparaissent souvent dans JavaDoc:

  • Liste des arguments qui n'existent plus
  • Pas d'explication de tous les arguments (les manquants ont probablement été ajoutés plus tard)
  • Des choses similaires pour les exceptions, etc.

En outre, il arrive parfois que des commentaires précisent "faites ceci ici pour améliorer les performances" lorsque la plupart des considérations relatives aux performances ont tendance à devenir obsolètes même plus rapidement que le code lui-même.


3
(Pas une critique - juste présenter une solution) Les avertissements de l'EDI peuvent grandement contribuer à empêcher cela. Si des mesures plus radicales sont nécessaires, échouez à la construction d’un avertissement / d’une erreur de construction javadoc.
Michael K

1
Cela pourrait expliquer pourquoi je n'en ai pas vu beaucoup. Je n'ai jamais travaillé quelque part qui utilise des commentaires de style JavaDoc.
Karl Bielefeldt le

4
@ Michael, les avertissements de l'IDE sont utiles dans les cas bénins. Notre base de code héritée produit plus de 20 000 avertissements Checkstyle, ce qui est bien au-dessus de la limite où vous ne faites plus attention: - (((Les IDE, lorsqu'ils sont mal utilisés, peuvent contribuer de manière significative à la misère de Javadoc. La plupart des conneries de Javadoc dans notre base de code étaient évidemment générées automatiquement.
Péter Török le

4

Je traite des commentaires obsolètes de temps en temps. Ce n'est certainement pas un mythe urbain. Les gens le mentionnent dans les listes des pires pratiques, non pas parce que cela vous frappe souvent, mais parce que cela vous coûte généralement beaucoup de temps et d’efforts.

Dans notre base de code, les commentaires les plus obsolètes sont dus à l'utilisation du modèle (anti) de description du comportement de la méthode près de son appel et non à la déclaration de la méthode. Cela se produit lorsque quelqu'un extrait un long morceau de code dans une méthode qui n'est appelée qu'une fois, puis commente l'appel de la méthode. Donc, vous vous retrouvez avec quelque chose comme ça:

featureList = GetFeatures();

// Sorting features and deleting empty ones from the list...
ProcessFeatures(featureList);

Et la méthode est déclarée quelque part ci-dessous sans commentaires. Les gens bousillent ces méthodes au fil des ans en modifiant les spécifications et en corrigeant les bogues, et vous finissez par vous retrouver avec une méthode qui ne trie pas la liste et génère une exception quand elle trouve la fonctionnalité vide. Le commentaire ci-dessus est donc un commentaire obsolète qui vous coûtera éventuellement du temps en débogueur. Cela se produit dans certaines bases de code.


3

Demandez-vous ceci. Avez-vous déjà modifié une ligne de code sans modifier les commentaires associés ou en ajouter de nouveaux?

J'ai travaillé avec beaucoup de code hérité et les commentaires ne sont parfois même pas pertinents.


2

Pour l'essentiel, mon expérience correspond à la vôtre, mais j'ai rencontré un cas où cela était vrai partout dans le code. C'était une application qui avait été écrite des années auparavant par un atelier de conseil qui n'était plus "en bons termes" avec le client.

La société a fait un travail exceptionnel en commentant le code, mais les programmeurs qui l’ont maintenu depuis le transfert initial faisaient partie de la mentalité du «seul changement qui nécessite absolument de changer», ce qui en soi n’est pas mauvais. Malheureusement, ils ont conservé la même attitude à l'égard des commentaires, ce qui a entraîné une assez grande déconnexion entre les commentaires et le code au fil du temps.


2

Je ne vois pas trop de commentaires descriptifs devenir obsolètes, mais je vois beaucoup de commentaires de TODO qui existent depuis des années. Je souhaite qu'ils soient comme des capsules de temps et dit quelque chose comme ça:

//TODO: In 15 years AND NO SOONER... actually implement this method.

1
Le problème dans ce cas est probablement l'utilisation abusive de TODO. Je pense que les TODO ne devraient être utilisés que lorsque le code est réellement fonctionnel, mais que des améliorations pourraient être apportées ultérieurement. Par conséquent, TODO: implementaucun type de commentaire ne devrait exister et le fait que personne ne soit vraiment revenu n'a pas d'importance. Malheureusement, peu de gens adhèrent à cette règle et je suis tout à fait d’accord que j'aimerais voir un commentaire comme celui que vous avez posté dans un code de production à un moment donné. Ça ferait ma journée.
pwny

1
En C #, j'utilise NotImplementedException à ces fins.
Steven Jeuris le

2
@pwny, je n'utilise que des TODO sur les choses que j'ai l'intention d'écrire avant mon enregistrement, pour m'assurer de les couvrir. Tout ce qui est à plus long terme que cela appartient à un bug tracker, à mon avis.
Karl Bielefeldt le

@ Karl Bielefeldt Cela a aussi beaucoup de sens.
pwny

2

Les 3 derniers projets sur lesquels j'ai travaillé, j'ai consacré plusieurs jours à supprimer tous les commentaires obsolètes, trompeurs et tout simplement inutiles de la base de code. Lorsque cela est possible et nécessaire, je les remplace par des commentaires plus appropriés, mais le plus souvent, il s'agit simplement de supprimer le commentaire et de passer à autre chose.

J'ai fait la même chose sur pratiquement tous les codes que j'ai jamais pris en charge, généralement après l'avoir laissé en suspens pendant un certain temps et après que les propriétaires d'origine soient partis depuis longtemps et / ou qu'ils ne veuillent pas ou ne soient pas en mesure de passer les commandes correctement.


1

Ce pourrait être le déclin dans l'utilisation des commentaires. Combien de code de quelqu'un est admissible? D'une part, quelqu'un doit réellement inclure des commentaires pour qu'il soit obsolète. Deuxièmement, le code qui a été commenté doit être changé. Pas sûr qu'un pourcentage élevé de code soit admissible.

Vous n'avez qu'à vous fier à un seul commentaire pour gâcher un gros morceau d'une application et perdre beaucoup de votre temps.


0

Dans une organisation qui produit beaucoup de code, il est difficile de synchroniser les commentaires. Le meilleur moyen de comprendre ce qui se passe consiste à utiliser des logiciels qui dessinent le diagramme de flux de contrôle du module sur lequel vous travaillez. C'est la seule façon de garder une idée de ce que le logiciel fait.

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.