是否有关于注释源代码对软件质量，可维护性和开发人员生产力的影响的经验研究？[关闭]

我主张对源代码进行评论并记录软件产品。根据我的个人经验和观察，在必须开发软件或维护软件的过程中，对经过严格注释的源代码进行的工作以不同的方式帮助了我。

但是，还有一个阵营说评论最终毫无价值，或者其价值值得怀疑。许多不加评论的编码支持者认为：

• 如果一段代码写得很好，那是自我解释，因此不需要注释
• 如果一段代码不是不言自明的，则对其进行重构并使其变得不言自明，以便它不需要任何注释
• 您的测试套件就是您的实时文档
• 随着时间的流逝，代码和注释不同步，这成为令人头疼的另一个原因
• 敏捷表示工作代码比大量文档更重要，因此我们可以放心地忽略编写注释

对我来说，这只是教条。再次，我个人的观察是，由才华横溢，经验丰富的开发人员团队编写的软件最终最终会产生大量不言自明的代码。

同样，Java API，Cocoa API，Android API等表明，如果您要编写和维护高质量的文档，则可以实现。

综上所述，基于个人信念的有关文档优缺点的讨论以及对源代码的评论通常不会以良好的结局而无法得出令人满意的结论。

因此，我正在寻找有关软件文档（尤其是注释源代码）对其质量和可维护性及其对团队生产力的影响的影响的学术论文和实证研究。

您是否偶然发现了此类文章？如果有的话，结果如何？

Woodfield，Dunsmore和Shen在1981 年的“模块化和注释对程序理解的影响”中发现，“程序中包含注释的对象比没有注释的对象能够回答更多的问题。”

但是，在“学习代码可读性的度量标准”（2010年）中，Raymond PL Buse和Westley Weimer发现注释仅对可读性和质量产生有限的影响：

从摘要：

我们构建了一个自动化的可读性度量，并且...表明该度量与软件质量的三个度量紧密相关：代码更改，自动化缺陷报告和缺陷日志消息...我们的数据表明，注释本身并不那么重要。而不是简单的空白行来判断本地可读性。

从第12页：

我们发现注释与注释者的可读性（相对能力为33％）仅具有良好的相关性。一个结论可能是，尽管注释可以增强可读性，但它们通常用于开始不那么可读的代码段中：注释和不可读的代码有效地平衡了。最终结果似乎是，注释本身并不总是表示可读性高或低。

请记住，“不带注释的编码”支持者并不是说不带注释的代码比带注释的代码更好。他们争辩说，一种不带注释的特殊代码风格 -一种将代码提取到具有自描述名称的方法中，一种引入解释变量的方法，一种具有良好测试套件的代码-比不执行这些操作的代码更好但有评论。这可能会使已完成的任何研究的适用性复杂化。