Existe-t-il des études empiriques sur les effets des commentaires du code source sur la qualité des logiciels, la maintenabilité et la productivité des développeurs? [fermé]

11

Je suis partisan de commenter le code source et de documenter les produits logiciels. D'après mon expérience personnelle et mon observation, travailler sur du code source rigoureusement commenté m'a aidé de différentes manières lorsque j'ai dû développer un logiciel ou le maintenir.

Cependant, il y a un autre camp qui dit que les commentaires sont finalement sans valeur ou que leur valeur est discutable. De nombreux partisans du codage sans commentaires soutiennent que:

  • Si un morceau de code est bien écrit, il est explicite et n'a donc pas besoin de commenter
  • Si un morceau de code ne s'explique pas de lui-même, refactorisez-le et expliquez-le de manière à ce qu'il n'ait pas besoin de commentaires.
  • Votre suite de tests est votre documentation en direct
  • Au fil du temps, le code et les commentaires se désynchronisent et cela devient une autre source de maux de tête
  • Agile dit que le code de travail est plus important que les piles de documentation, nous pouvons donc ignorer en toute sécurité l'écriture de commentaires

Pour moi, ce n'est qu'un dogme. Encore une fois, mon observation personnelle a été que les logiciels écrits par des équipes de développeurs intelligents et expérimentés se retrouvent finalement avec une quantité considérable de code qui n'est pas explicite.

Encore une fois, l'API Java, l'API Cocoa, l'API Android, etc. montrent que si vous voulez écrire et maintenir une documentation de qualité, c'est possible.

Cela dit, les conversations sur les avantages et les inconvénients de la documentation et les commentaires sur le code source qui sont basés sur des croyances personnelles ne se terminent généralement pas bien et ne mènent à aucune conclusion satisfaisante.

En tant que tel, je recherche des articles universitaires et des études empiriques sur les effets de la documentation du logiciel, en particulier en commentant le code source, sur sa qualité et sa maintenabilité ainsi que ses effets sur la productivité de l'équipe.

Avez-vous trébuché sur de tels articles et quel en a été le résultat, le cas échéant?

Behrang Saeedzadeh
la source
2
Je pense que c'est une question intéressante de toute façon, mais je ne suis pas très surpris qu'elle puisse se fermer ici. C'est pourquoi j'ai également publié ceci sur Quora.
Behrang Saeedzadeh
4
@gnat - Il me semble que "quelles recherches ont été faites dans cet aspect du domaine du développement logiciel?" est une question assez différente de celle des demandes "veuillez me donner des livres sur un sujet" qui ne sont pas tout à fait les bienvenues.
Josh Kelley
1
Juste à la lecture du titre: Il n'y a pas d'études empiriques sur les effets de quoi que ce soit sur la qualité. S'il y en avait, ce site n'existerait pas.
Euphoric
2
@Euphoric vos deux déclarations se contredisent. Si nous ignorons le document "fou" de 30 ans, il n'y a pas de conflit. Mais de toute façon, nous ne devons pas ignorer les résultats simplement parce qu'ils sont anciens, mais évaluer de manière critique leur relation avec le travail moderne (comme nous devrions le faire avec de nouveaux résultats également).
3
@Euphoric Je souhaiterais que vous postez cela comme réponse, afin que je puisse minimiser votre manque total de recherche dans votre affirmation générale. Il existe des tonnes d'articles et de recherches, empiriques et autres, sur les effets de différentes techniques sur la qualité des logiciels. Avez-vous étudié quelque chose sur le génie logiciel?
Andres F.

Réponses:

9

Dans «L'effet de la modularisation et des commentaires sur la compréhension des programmes» (1981), Woodfield, Dunsmore et Shen ont constaté que «les sujets dont les programmes contenaient des commentaires pouvaient répondre à plus de questions que ceux sans commentaires».

Cependant, dans «Learning a Metric for Code Readability» (2010), Raymond PL Buse et Westley Weimer ont constaté que les commentaires n'ont qu'un effet limité sur la lisibilité et la qualité:

Du résumé:

Nous construisons une mesure de lisibilité automatisée et ... montrons que cette métrique est fortement corrélée à trois mesures de la qualité logicielle: les changements de code, les rapports automatisés sur les défauts et les messages du journal des défauts ... Nos données suggèrent que les commentaires, en eux-mêmes, sont moins importants que de simples lignes vierges à des jugements locaux de lisibilité.

À partir de la page 12:

Nous avons constaté que les commentaires n'étaient que modérément bien corrélés avec la notion de lisibilité de nos annotateurs (puissance relative de 33%). Une conclusion peut être que même si les commentaires peuvent améliorer la lisibilité, ils sont généralement utilisés dans des segments de code qui ont commencé moins lisibles: le commentaire et le code illisible s'équilibrent efficacement. L'effet net semblerait être que les commentaires ne sont pas toujours, en eux-mêmes, indicatifs d'une lisibilité élevée ou faible.

Gardez à l'esprit que les partisans du «codage sans commentaires» ne disent pas que le code sans commentaires est meilleur que le code avec commentaires. Ils soutiennent qu'un style de code particulier sans commentaires - celui qui extrait le code dans des méthodes avec des noms auto-descriptifs, celui qui présente des variables explicatives , celui qui a une bonne suite de tests - est meilleur que le code qui ne fait pas ces choses mais a des commentaires. Cela pourrait compliquer l'applicabilité de toute étude réalisée.

Josh Kelley
la source
1
L'article de Woodfield et al. Porte sur une variété particulière de commentaires, à peu près équivalente à ce que l'on pourrait maintenant appeler Javadoc: "Plus précisément, cette recherche tente de déterminer si de courts commentaires, insérés juste avant un module logique, peuvent aider à la compréhension en décrivant brièvement la fonction. du module logique et aider à définir les limites du module logique. "
J'aurais dû ajouter à l'époque: cela ne veut pas dire qu'elle n'a pas de valeur, en effet c'est une étude intéressante et bien construite. Je pensais juste qu'il fallait dire qu'ils n'acceptaient pas tous les commentaires.