documentation - 我应该记录我的私有方法吗？

Question

私有方法文档只能由有权访问源代码的人查看。值得为此付出的努力吗？

score 78 · Accepted Answer

个人感觉是这样的。文档通常对未来维护您的软件的开发人员最有用——尤其是成员文档。

甚至公共 API 文档也仅限于开发人员以外的任何受众。为以下人员提供文件 - 他们会感谢您。

score 15 · Accepted Answer

绝对是。除了琐碎的软件之外，您可以通过正确使用注释来更快地理解代码，即使是几个月后的原作者也是如此。

score 14 · Accepted Answer

为了清晰起见，您应该重构代码，这样就不需要实现文档。

不要利用你的能力来评论你的代码，让你一开始就懒惰地编写明显的代码。

说明与您的代码相同但使用不同语言的文档是多余的。和冗余代码一样，这种冗余也必须保持，但通常不是。

score 11 · Accepted Answer

对对对。记录您编写的任何代码。

最终有人会维护您编写的代码。文档是您帮助他们进入编写特定代码时的心态的一种方式。私有函数对文档特别重要，因为它们在代码中的使用量往往最少，开发人员可以从中推断出它们的不变量。

score 8 · Accepted Answer

当然是。六个月后，您可能需要回来进行一些维护。一些恰如其分的评论可以为您节省大量时间和精力。您可能不需要像公共 API 那样记录它，但一些评论永远不会受到伤害。

score 7 · Accepted Answer

7

任何复杂到既有趣又不明显的方法都值得花时间通过一些文档来澄清它。

于 2009-11-16T17:38:12.177 回答

score 6 · Accepted Answer

我不会。如果您的私有方法需要文档，则可能值得花时间在这方面使您的代码更清晰。

编辑：即使有摘要我也不会记录。私有方法可以改变、重新萌芽、消失。OO 的基本原则之一是封装。您不需要知道私有方法在做什么。至于开发人员，谁来更新所有这些文档？第一次你，但在未来？

编辑2：来自评论

我强烈反对。唯一不应该（以某种方式）记录私有方法的情况是，当它的目的从它的名称和源代码中完全显而易见时。如果您的代码有任何“聪明”之处，则值得评论解释您为什么这样做。

我非常同意，但是.. 代码不应该是“聪明的”，代码应该是功能性和可读性的。大多数时候，您的目标应该是尽可能让您的代码对读者透明，如果您需要对其进行注释，那么您应该在点击 javadoc（或您使用的任何内容）之前让您的代码更清晰。

编辑3：

你更愿意看到什么。？

/**
*   This method doesn't do what you expect it to.
*   Below you will find a whole ream of impenetrable
*   code. Where there are bits that look that they do x, they don't
*   they do y. 
**/
private void someComplexInternalMethod()
{
     ...
     badly named variables
     comments to describe intent
     perhaps some out of date orphaned comments
     as code has been removed but comment remains

     ....
     ....
     looong methods 
}

private void WellNamedMethod()
{
     ...
     well named variables
     shorter method, highly cohesive
     self documenting
}

score 4 · Accepted Answer

当您在 6 个月后访问您的私人方法时，它们对您来说是否会像现在一样有意义？您是否需要花费数小时试图追踪组件之间的关系？

根据我的经验，好的文档绝不是浪费时间。

score 4 · Accepted Answer

绝对地。始终假设您将在两年后对其进行修改，从而编写代码。方法总结是最重要的。我无法告诉你有多少次因为我正在编写文档（摘要、参数、返回）而发现错误并意识到我错过了一些东西。

score 3 · Accepted Answer

是的，有必要记录您的私有方法。随着越来越多的开发人员使用您的代码并修改您的代码，它变得越来越必要。私有方法保证特定的功能，就像公共方法一样。不同之处在于代码的使用方式。私有方法的文档可以加速重构。

score 3 · Accepted Answer

记录公共方法对维护者和使用你的包的人都很有用。

记录私有方法对维护者或您的包（包括您）很有用。

简而言之，它的必要性略有不同。例如，记录私有方法不需要是正式的。

score 3 · Accepted Answer

我会采取不受欢迎的立场，说不。

否则，我的许多私有方法将是方法中的复杂语句，需要注释的语句。使它们成为私有方法的一半原因是为了澄清代码并减少记录其作用的需要。

每当代码更改时，都需要维护和更新文档。您现在要求维护开发人员两次执行相同的工作。一次修复错误，一次解释修复。

以我的经验，第二个动作通常不会发生。当我从这里开始时，我继承了一个 5 年以上的代码库。在一个特定的应用程序中，大约一半的内容都被注释了，通常——非常频繁地——注释与实际代码几乎没有相似之处。要么这个家伙在写它们的时候很生气，要么他用第一段代码写了评论，然后代码改变了，而评论却没有。

现在我几乎没有阅读他的评论。每个应用程序或大型应用程序中的逻辑模块都有一个 1 或 2 页的文档，概述了它的一般用途、一般结构和任何不寻常的东西。

我们希望开发人员能够编写可读的代码，而新员工能够阅读可读的代码。

现在，让投票开始吧！

score 1 · Accepted Answer

就我个人而言，我更相信在代码文档中的自我记录代码。大量使用意图显示名称、无副作用函数等。

但有时不可能让代码自我记录，在这种情况下，我将始终记录功能或内部工作原理。

score 0 · Accepted Answer

好吧，那个代码也应该是可维护的，你不觉得吗？当然，他们应该记录在案！您将不得不在几个月内查看该代码，并且在进行更改时您将希望有一些东西可以参考。

score 0 · Accepted Answer

如果您的方法名称没有使它们的目的立即显而易见，那么它们的名称就不是很好。依赖于有名的类和方法的文档总是会回来咬你。所需要的只是一些人们忘记更新文档的例子，而你最终会陷入可怕的混乱。例子：

坏的

private void Update(string sValue, DateTime dValue)
{...}

更好的

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate)
{...}

第二个版本需要记录什么？该名称标识了它的目的是什么，参数名称使预期传递的内容一目了然。

如果您的方法又长又复杂，以至于它们需要一本小说来解释，您需要将它们分解为功能的逻辑位，这些功能可以命名良好且高度集中。恕我直言，这比一些写得不好的内联文档更容易理解，这些内联文档可能是最新的，也可能不是最新的——我仍然会通读所有代码，以确保它与文档所说的相匹配，并且在大多数情况下，我会假设文档尚未维护并忽略它。

您还应该进行单元测试来调整代码并使功能更加明显。对于命名良好的类、方法和单元测试，附加文档的用途是什么？

score 0 · Accepted Answer

是的。作为这个笑话，我听到了：

编程就像性。一个错误，你必须支持它到你的余生。

score 0 · Accepted Answer

对于公共接口（例如公共方法和类），记录每个方法的用途——您希望尽可能清楚地描述您的公共接口（即您的代码协定）。

对于私人成员（您将在其中实际工作），您可能希望记录方法的目的。但是记录你的算法更有用——为什么和如何，而不仅仅是对代码的描述。

任何可以访问您的私人成员的未来开发人员也将可以访问您的代码。如果我能读懂你的代码，我就能弄清楚它在做什么。但是除非我能读懂你的想法，否则我无法弄清楚你的代码为什么会做它正在做的事情——除非你写一些文档来解释它。

score 0 · Accepted Answer

0

只有当你没有更好的事情可做时。因此 - 可能 - 不。

于 2009-11-16T18:09:59.383 回答

score 0 · Accepted Answer

（反对共识）我强调自我记录代码（公共但私有）。这可能非常有效，您需要的正式文档要少得多。有些人真的不喜欢这个（有时是有充分理由的）。由于您提到了私有实现，因此随着时间的推移重命名和修改的约束要少得多。带有少数特殊情况的接口是失败的秘诀（但它们仍然会产生）。

文档：如果它要消耗大部分标头，最好是有意义的。

我有删除坏/无意义的文档的习惯，因为就像界面一样，没有比坏更好的了。呵呵

score 0 · Accepted Answer

这些天来，我经常在开始编写代码之前编写类/方法级别的文档。这对于保持类的良好定义和方法的单一用途特别有用，因为您面前有一个提醒，当您的类/方法超出您的初衷时，它会告诉您。

我不喜欢编写文档，而不是任何可以编写代码的人，但是我发现它不会占用编码/调试时间，因为向自己解释你将要做什么的行为就是改进从你的思考时间输出。

方法注释还提供了有用的双重检查，因为如果代码没有按照注释所说的那样做，那么在调试时这是值得研究的。

从代码阅读者的角度来看，由于有用代码的阅读次数比编写次数多很多（成百上千），因此记录代码合同的注释使读者不必在下一个细节层次上弄清楚代码做了什么。当您略读数千行代码时，这可以节省从略读到分析再返回的昂贵的心理上下文切换。

花费大部分工作日阅读大量代码的人是负责保持系统正常工作并代表其开发团队与管理层进行谈判的团队领导和架构师。即使是写得很好的代码也很难快速大量阅读，因为大部分代码的抽象级别与读者感兴趣的级别不同。

如果代表开发团队的人不能快速阅读代码，就很难与经理进行基于证据的讨论，并且决策是在不受技术现实影响的情况下做出的。

重复多次，这会给开发团队带来困难的问题，这可以通过在详细级别应用一些工程纪律来避免。

并非所有系统都庞大、复杂且缺乏只知道答案的专家，但有些系统就是这样，而且它们可以突然变成那样。下一代培训大师将感谢您记录您的代码。

score 0 · Accepted Answer

私有领域呢？对于 Serializable 类，必须记录私有字段。来自 Johsua Bloch 的“Effective Java”：

私有字段定义了一个公共 API，它是类的序列化形式，这个公共 API 必须记录在案。@serial 标记的存在告诉 Javadoc 实用程序将此文档放在记录序列化表单的特殊页面上

documentation - 我应该记录我的私有方法吗？

21 回答 21

Related

Reference