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?
la source
Réponses:
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é:
À partir de la page 12:
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.
la source