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