我应该记录我的私人方法吗？

Question

只有谁有权访问源代码才能看到私有方法文档。是否值得花费在它上面的努力？

Answer 1

就个人而言，我觉得确实如此。文档通常对未来维护软件的开发人员最有用 - 尤其是成员文档。

即使是公共API文档，对开发人员以外的任何其他人只有有限的用途。以下人员的文件 - 他们会感谢你。

Answer 2

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

Answer 3

为了清晰起见，您应该重构代码，以便不需要实施文档。

不要使用你的能力来评论你的代码，以免你在编写明显的代码时懒惰。

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

Answer 4

是的，是的，是的。记录您编写的任何代码。

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

Answer 5

是的，当然。在六个月内，您可能需要回来做一些维护。一些好的评论可以为您节省大量的时间和精力。您可能不需要在公共API的范围内记录它，但一些评论永远不会受到伤害。

Answer 6

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

Answer 7

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

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

Answer 8

绝对。始终编​​写代码时假设两年后你需要修改它。方法摘要是最重要的。我不能告诉你有多少次我抓到了bug，因为我正在编写文档（摘要，参数，返回），并意识到我错过了一些东西。

Answer 9

我不会。如果您的私人方法需要文档，则可能值得花时间在此区域中使代码更清晰。

编辑：即使有摘要我也不会记录。私人方法可以改变，重新萌芽，消失。 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
}

Answer 10

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

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

简而言之，这是一种略微不同的方式。例如，记录私有方法不需要是正式的。

Answer 11

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

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

需要维护文档＆amp;代码更改时更新。您现在要求维护开发人员两次执行相同的工作。一旦修复bug，一次​​解释修复。

根据我的经验，第二次行动通常不会发生。我从这里开始时，我继承了一个5岁以上的代码库。在一个特定的应用程序中，大约一半的所有内容都经过评论，通常 - 非常频繁 - 评论与实际代码几乎没有相似之处。这个家伙在写作时都是酸性的，或者他用第一段代码写了评论，然后代码改了，评论没有。

现在我几乎没有阅读他们的意见。大型应用程序中的每个应用程序或逻辑模块都有一个1页或2页的文档，概述了它的一般用途，一般结构和任何与众不同的内容。

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

现在，让投票开始吧！

Answer 12

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

Answer 13

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

但有时不可能让代码成为自我纪录片，在这种情况下，我将始终记录函数或内部工作。

Answer 14

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

  

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

Answer 15

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

我不喜欢编写文档而不是其他任何可以编写代码的人，但是我没有发现它会占用编码/调试时间，因为向你自己解释你将要做的事情的所有行为都是关于改善思考时间的输出。

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

从代码阅读器的角度来看，由于有用代码的读取次数比其编写的次数多（数百/数千），因此记录代码合同的注释使读者无需计算代码在下一级别执行的操作细节。当你浏览数千行代码时，这可以节省昂贵的心理上下文切换，从略读到分析再回来。

那些花费大部分工作时间阅读大量代码的人是团队领导和架构师，他们负责保持系统正常运行，并代表他们的开发团队与管理层进行协商。即使是编写良好的代码也难以快速和大量阅读，因为它的大部分内容与读者感兴趣的水平处于不同的抽象层次。

如果代表开发团队的人员无法快速阅读代码，则很难与经理进行基于证据的讨论，并且决策的制定不会受到技术现实的影响。

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

并非所有系统都是大型的，复杂的，并且只是知道答案的大师，但是有些系统就是这样，他们可以突然这样做。下一代培训大师将感谢您记录您的代码。

Answer 16

（违背共识）我强调自我记录代码（公共虽然私有）。这可能非常有效，您需要正式记录更少。有些人真的不喜欢这个（有时候是有充分理由的）。由于您提到了私有实现，因此随着时间的推移重命名和修改的约束要少得多。具有少数特殊情况的界面是失败的一种方法（但它们仍在制作中）。

文档：如果它将消耗大部分标题，那么最好有意义。

我习惯于删除糟糕/无意义的文档，因为像界面一样，没有比坏更好的东西。和合

Answer 17

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

Answer 18

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

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

任何有权访问您的私人成员的未来开发者也可以访问您的代码。如果我能阅读你的代码，我可以弄清楚它在做什么。但除非我能读出你的想法，否则我无法弄明白为什么你的代码会做它正在做的事情 - 除非你写一些文档向我解释。

Answer 19

是。我听到这个笑话：

  

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

Answer 20

如果你的方法名称没有立即明显，那么它们的命名就不好了。 依赖于命名良好的类和文档。方法总会回来咬你。所需要的只是一些人忘记更新文档并最终导致可怕的混乱。 例如：

<强> BAD

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

<强>更好

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

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

如果你的方法如此漫长而复杂，以至于需要一本小说来解释，你需要将它们分解为可以命名和高度集中的逻辑功能。恕我直言，比一些写得不好的内联文档更容易理解，这些文档可能是也可能不是最新的 - 我仍然会阅读所有代码，以确保它与文档说应该做的相符。在大多数情况下，我会假设文档没有被维护并忽略它。

您还应该进行单元测试，以便对代码进行灵活处理，使功能更加明显。有充分命名的类，方法和单元测试，其他文档的用途是什么？

Answer 21

那么，代码也应该可以维护，你不觉得吗？当然应该记录下来！您将不得不在几个月内查看该代码，并且在进行更改时您会想要提及某些内容。