有关代码文档生产率收益/损失的研究

经过大量搜索，我未能回答与软件开发领域中已知的假设有关的基本问题：

什么是已知的：

对足够的代码文档（无论是Doxygen标记，Javadoc还是仅仅是大量注释）实施严格的政策，都会增加开发代码所需的时间。

但：

拥有详尽的文档（甚至API），可以在新手和经验丰富的开发人员添加功能或修复bug时带来生产率的提高（有人认为）。

问题：

保证此类文档所需的额外开发时间是否能被下游生产率的提高（从严格的经济意义上来说）所抵消？

我正在寻找案例研究或答案，可以带给他们客观的证据来支持得出的结论。

提前致谢！

文章“印刷风格不只是装饰风格”比较老，但它很有趣：http : //portal.acm.org/citation.cfm?id=78611。

很老，它不包括如今可能出现的所有奇特的东西，但它清楚地表明代码文档确实很重要。

对于像我一样无法访问ACM数字图书馆的人，他们创建了两组程序员，并为他们提供了相同的代码来学习。A组仅收到带有常规注释的代码，B组收到了漂亮的印刷清单，其中包含目录，交叉引用以及1990年可能出现的所有细节。

然后，他们要求两组人员对代码执行某些任务（例如，扩展功能，查找错误，...），并根据答案的速度和质量对它们进行评分。

为了平衡团队，他们拥有相同数量的专家和初级程序员。

好吧，事实证明，在众多测试中，B组（列表上印有漂亮字样的）始终比A组更好。而且，在特定情况下，只有A组中最熟练的人才能超过B组的初级程序员。

该文章说的更多，但这是我可以从内存中回忆的内容（我仍然应该将印刷的文章放在某处）。

至少对我而言，似乎显而易见的是，可读代码比文档的价值要高得多，后者仅是为了弥补写得不好的代码。我倾向于将代码中的注释视为挑战，以查看是否可以通过重写代码来删除注释，并使注释更具自我解释能力。

除了常识之外，我没有任何确凿的证据来支持这一点。

我没有任何研究要引用，但我确实有一条简单的规则：如果两周后回到我的代码并且无法立即弄清楚我做了什么，它要么需要更多注释，要么需要简化。

当然，如何你的代码的作品，应通过代码本身记录。但是花时间写评论，仔细而简洁地解释为什么编写代码的原因从长远来看几乎可以肯定是值得的，即使您是唯一维护代码的人。

一个软件的生命周期将主要花费在维护阶段，因此，任何可以帮助程序员了解您正在发生的事情的东西几乎都可以肯定地带来财务收益，因为它可以帮助开发人员加快速度。

在稍微不平凡的任何API上，在代码中记录API几乎是无用的。这是因为API的强大之处在于它作为一个整体如何协同工作（而不是各个方法/对象的工作方式）。

因此，比真正的文档更有帮助的是类似菜谱的文档，它解释了API的预期使用模式，以及有关如何解决某些明显情况（使用大多数（不是100％）API）的示例。

到可能已经没有发明出来的一个给定的方法是否是决定，无需工具，太主观要求的单据被写入。

任何最佳实践，例如“所有公共方法”或给定程序包中的所有类等，都可能有所帮助，但过于粗糙，无法推荐超出特定用例的范围。

我的建议：教您的开发人员良好做法，如何确定对文档很重要的方法（正式或非正式API，常用，存根方法，复杂或深奥的）并让他们自行管理。

（密切相关：编码标准中是否有太多的统一性？）

^{抱歉，我没有任何研究可引用，但我怀疑这是一个问题，任何试图衡量它的尝试都会对结果产生太大影响，以至于无法得出一般性结论。}

我认为在这方面，我们需要将“常规”代码与公共API分开。对于常规代码，我已经与其他大多数答复者非常一致，因为代码应该是自我记录的，并且读起来就像散文一样。如果我的代码不是那样，通常是我的错，因此应该重构它，而不是进行文档记录。小型方法一次只做一件事，在一个抽象级别上工作，并具有正确的描述性名称，可以为实现这一目标提供一条好方法。

评论的问题是它们烂了。添加注释后，它便开始独立于其附带的代码而生活。下一个修改代码的开发人员也将忠实地更新相关注释的机会有多大？以我的经验，接近零。经过一些修改后的最终结果是，该评论使人们感到困惑或误导，而不是帮助他们。

可能的例外是性能优化的代码或使用特定的算法。在这种情况下，添加注释以描述为什么代码看起来像是有用的，对算法的引用等。

关于此主题的开创性工作是“ 干净代码”。

OTOH，一个公共API确实也应该在Javadoc中得到很好的文档说明。由于无数技能和假设千差万别的陌生人可能会使用它，因此必须采取一切预防措施，使其尽可能简单和明确。在很大程度上，这仍然是正确API设计的问题，但是文档也起着重要的作用。

问题是您是否通过记录代码来节省时间，而随后的每个开发人员都必须尝试弄清楚这样做是什么。如果您的代码通过代码审查而没有任何人提出关于其功能的任何疑问，那么您可能处于良好状态。描述您对输入所做的假设并不难。假设您的方法接受一个整数对象并返回一个字符串对象。int可以为null吗？是否有最小/最大值（除integer.MinValue / MaxValue之外）？它可以返回空字符串或null吗？是否抛出任何异常？当然，任何人都可以通过检查找到它们，但是如果足够多的其他开发人员将使用您的代码，则节省几分钟的时间非常值得您花时间。而且，它使测试人员可以创建测试来确认代码。

这无疑是一个有趣的话题，因为一直存在关于开发人员是否应该花时间创建或维护文档的争论，但事实是，代码应该写得很好，并且要很好地进行注释，这样，当开发人员比他（她）重新访问代码时不必花时间去思考代码的编写方式以及首先应该做的事情，如果新团队成员加入团队，那么他也将无法理解代码已被明确记录的功能和工作。

因此，应该对代码进行很好的注释，并且应该是不需要任何外部文档的自文档代码。

在我的职业生涯中，我看到过代码具有不同级别的文档和质量（请注意，文档和质量是常规的关注点）。我希望将花费在文档上的时间用于提高质量。对于简单的情况，有一些工具，例如GhostDoc，可以查看功能并为您生成文档注释。如果GhostDoc能够生成有意义的注释来说明您的功能，那么您显然已经实现了拥有功能明确的功能的目标。

在许多情况下，GhostDoc甚至无法开始告诉您函数实际上是做什么的。您最好将时间花在解决该问题上，（也许）使用ghostdoc自动生成代码。

有关更深入的讨论，请参见Bob Martin的Clean Code和PPP。