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

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?

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.

"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.}

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

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.

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.

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.

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.

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.

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.

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.

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.