logo标签列表

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

documentationprivate-members
46

私有方法文档只能被访问源代码的人看到。花费精力编写它是否值得？

12
如果你对它们发表评论，那它们就不太私密了，对吧...... - Citizen
@Citizen：哈哈，非常有趣的观点 :P！ - Andreas Grech
21个回答
80

我个人认为它是必要的。文档通常对维护你的软件的未来开发人员非常有用，尤其是成员文档。

即使公共API文档对于除开发人员以外的任何受众来说也只有有限的用处。为那些后继者撰写文档——他们会感谢你的。

12
我同意，我讨厌那种“函数名可以很明显反映其功能”的说法。getX()显然不需要解释，但是calculateX()可能需要。 - amischiefr
嗯...为什么会被踩呢？只是好奇... - Reed Copsey
5
我认为许多人不同意，并且对于方法calculateX的Javadoc，“计算X”这样的描述并没有真正帮助任何人。 - IAdapter
4
“计算X”这样的评论会让我感到烦恼，不是因为它没有必要，而是因为它不够具体。X是如何被计算的？这似乎非常重要。即使是getX() - 它也不应该是“获取X”，而应该是对在此上下文中“X”代表什么的描述。 - Reed Copsey
3
如果可能的话，我总是尽量通过编写易读的代码来避免进行任何评论。如果不可能做到这一点，我会添加注释。 - Nick Weaver
1
@ReedCopsey，您不认为calculateX本身就是一个糟糕的标识符吗？它应该是find...OfX，甚至更好的是find...Of（...）。在这种情况下，您将不需要文档，因为名称不会产生歧义。 - Dioxin
16

当然可以。在任何不是微不足道的软件中，只要正确使用注释，甚至对于几个月前的原作者来说，都可以使代码更容易理解。

16

你应该重构代码以提高其清晰度，使得实现文档变得不再必要。

不要依赖注释来避免在一开始就懒得写明显的代码。

用另一种语言表达与代码相同的内容的文档是多余的，就像冗余的代码一样，这种冗余也需要维护，但通常并没有被维护好。

9
可以编写代码使其在 做什么 方面很明显，但通常我们不能让 为什么 这样做变得很明显。 - NVRAM
4
为什么、什么和如何是描述同一事物的不同抽象级别。调用方法的代码是“为什么”，方法签名本身定义了“什么”，而方法内部的代码定义了“如何”。所以，一个特定方法为什么会做它所做的事，在调用该方法的代码中变得明显。 - Doug Knesek
很好的观点，Doug。仅在非常复杂的方法和编写这些方法的人不正确地命名它时，才有意义的是什么/为什么参数。 - IAdapter
11

是的，是的，是的。记录你写的任何代码。

迟早有人将维护你编写的代码。文档是帮助他们进入你写特定代码时的思维方式的一种方式。特别需要记录私有函数，因为它们往往在代码中使用最少，开发人员难以推断它们的不变量。

并不是所有的代码都需要被记录。有一条规则指定了哪些需要被记录，哪些不需要。您认为每个单独的getter和setter（不包括复杂的getter和setter）都应该被记录吗？ - monksy
4
记录你所编写的代码，而非每一行。一个合理的注释可以很有意义地解释为什么我提供这些setter和getter方法。我的口号是：注释应该增加价值。"@param i 这是一个int类型的参数"比不注释还要糟糕。 - deft_code
只有当你写的每个注释都非常有用，并且比代码更好时，你才是正确的。但是，如果注释比代码更糟糕... - IAdapter
8
我不会这么做。如果您的私有方法需要文档，可能值得花时间在这个领域使您的代码更清晰。
编辑：即使有摘要，我也不会记录。私有方法可能会更改、新建或消失。面向对象的基本原则之一是封装。您不需要知道私有方法正在做什么。至于开发人员，谁将更新所有这些文档？第一次你放入未来？
编辑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
}
我不是指内联注释，而是方法摘要。 - Jader Dias
4
@John Nolan: 我强烈不同意。只有在私有方法的目的从其名称和源代码中完全明显时，才不需要以某种方式记录它。如果您的代码中有任何“聪明”的地方，它都应该得到一个注释，解释为什么以那种方式编写代码。 - Daniel Pryden
1
@Daniel Pryden - 我非常同意你的观点。 - Johnno Nolan
8

是的，绝对需要。在六个月后，您可能需要回来进行一些维护。几个恰当的注释可以节省您大量的时间和精力。您可能不需要像公共API那样详细记录它，但是一些注释从未伤害过。

7

任何复杂且有趣而又不明显的方法都值得花时间通过文档来澄清。

4

当你在6个月后访问自己的私有方法时，它们是否和现在一样易于理解？你是否需要花费数小时来追踪组件之间的关系？

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

4

当然。编写代码时应该假定两年后你需要对其进行修改。方法摘要是最重要的。我无法告诉你有多少次因为编写文档（摘要、参数、返回值），我才发现自己漏掉了某些东西，从而捕捉到了错误。

2
同意，在用通俗的语言解释时就已经有价值了。俗话说得好：“如果你真的想理解某个东西，你需要能够清楚地向他人解释它。” - Ophidian
是的，我考虑过提到这一点。我曾经为一个使用所谓“Dummy Method”的人工作过。这个想法是，向一个腹语师的木偶解释你的程序/函数/任何东西的作用。当然，木偶不懂编程：他只是一个木偶。如果你不能向木偶解释清楚，那就说明你自己也没有理解透彻。 - Hugh Brackett
3

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

1
给那位点踩的用户：请解释一下你为什么不同意。 - monksy
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接