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é]

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?

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.