您是否为您编写的每种方法使用Javadoc？

我应该为所有java方法编写Doc Comments吗？

1> VonC..：

---

@Claudiu

当我编写其他人将使用的代码时 - 是的.其他人可以使用的任何方法(任何公共方法)都应该有一个javadoc,至少说明它的明显目的.

@Daniel Spiewak

我彻底记录了每个API类中的每个公共方法.具有公共成员但不打算用于外部消费的类在javadoc类中突出显示.我还记录了每个API类中的每个受保护方法,但程度较小.这是因为任何扩展API类的开发人员都已经对所发生的事情有一个公平的概念.

最后,为了自己的利益,我偶尔会记录私有和包私有方法.我认为在其使用中需要一些解释的任何方法或领域都将收到文档,无论其可见性如何.

@Paul de Vrieze

对于像琐碎的getter和setter这样的东西,在那之间分享评论并描述属性的目的,而不是getter/setter的目的

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

是的,这是更多的工作.

@VonC

当你打破一个巨大的复杂方法(因为高圈复杂性的原因)成:

一种公共方法叫

几种代表公共内部步骤的私有方法

,javadoc私有方法也非常有用,即使该文档在javadoc API文件中不可见.
但是,它允许您更容易地记住复杂算法的不同步骤的精确性质.

请记住:限制值或边界条件也应该是javadoc的一部分.

另外,javadoc比简单的"// comment"更好:

它被IDE识别,用于在将光标移动到 - javadoc-ed - 函数之一时显示弹出窗口.例如,一个常量 - 即私有静态最终变量 - 应该有一个javadoc,特别是当它的值不是微不足道时.例证:regexp(它的javadoc应该包含非转义形式的正则表达式,目的是什么以及正则表达式匹配的文字示例)

它可以通过外部工具(如xdoclet)进行解析

@Domci

对我来说,如果有人会看到它与否并不重要 - 我不太可能知道几个月之后我写的一些模糊代码.[...]
简而言之,评论逻辑,而不是语法,只在适当的地方进行一次.

@Miguel Ping

为了发表评论,你必须先了解它.当你试图评论一个函数时,你实际上正在考虑方法/函数/类的作用,这使你在javadoc中更加具体和清晰,这反过来又让你编写更清晰简洁的代码,这很好.

2> tunaranch..：

---

如果该方法明显不言自明,我可以跳过javadoc评论.

评论喜欢

/** Does Foo */
 void doFoo();

真的没那么有用.(过于简单的例子,但你明白了)

---

访问者和变更者可能需要评论,例如/**用户名.不包含az,Az以外的符号且不大于50个字符*/String getFirstName();/**设定价格.应该是正数,小数点后精度降低到4位**/void setPrice(双倍价格);

3> Daniel Spiew..：

---

我彻底记录了每个API类中的每个公共方法.具有公共成员但不打算用于外部消费的类在javadoc类中突出显示.我还记录了每个API类中的每个受保护方法,但程度较小.这是因为任何扩展API类的开发人员都已经对所发生的事情有一个公平的概念.

最后,为了自己的利益,我偶尔会记录私有和包私有方法.我认为在其使用中需要一些解释的任何方法或领域都将收到文档,无论其可见性如何.

---

我认为,为了彻底而记录每一种方法都是一个坏主意.它会导致杂乱,质量差的文档.代码应尽可能自我描述.将文档放在上面对你和读者来说都是浪费时间.噪音水平的提高使得很难看到真正重要的文档.无意义文档的数量增加了文档在不更新的情况下变得过时的可能性."setName()设置名称.\ @param name要设置的名称." "getName()获取名称.\ @return名称."

---

"为了我自己的利益,我偶尔会记录私有和私有方法".如果你是唯一一个会查看代码的人,那就没问题了.

---

"具有公共成员但不打算用于外部消费的类在javadoc类中突出显示." < - 你如何标记它们？

4> Paul de Vrie..：

---

对于像琐碎的getter和setter这样的东西,在那之间分享注释并描述属性的目的,而不是getter/setter.

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

是没有用的.更好地做一些事情:

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

是的,这是更多的工作.

5> volley..：

---

其他所有基地已经覆盖; 另外一个说明:

如果你发现自己这样做:

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

考虑将其改为:

void launchBlaardhIntoBleeyrg() { ... }

这似乎有点明显,但在许多情况下,您自己的代码很容易错过机会.

最后请记住,并不总是想要改变; 例如,可以预期该方法的行为会随着时间的推移而发展(请注意JavaDoc中的"当前"一词).

6> Jason..：

---

不,不要评论每个方法,变量,类等.

以下是"清洁代码:敏捷软件工艺手册"的引用:

有一条规则说每个函数都必须有一个javadoc,或者每个变量都必须有一个注释,这简直太愚蠢了.像这样的评论只会使代码变得混乱,暴露谎言,并导致一般的混乱和混乱.

如果且仅当它为方法,变量,类等的预期用户添加重要信息时,应该存在注释.什么构成"重要"值得考虑并且可以提醒我自己何时/如果我回来这个方法/类/等等,该方法的结果/副作用,为什么事物甚至存在的动机(在一些代码克服某些库或系统的缺点/错误的情况下),关于性能的重要信息或者什么时候适合打电话等.

什么不是一个好的评论,但表明代码本身应该被重写/修改是一个注释,解释复杂和模糊的方法或功能的细节.相反,更喜欢更清晰的代码.

7> Miguel Ping..：

---

还有另一个原因你应该使用javadocs.为了发表评论,你必须先了解它.当你试图评论一个函数时,你实际上正在考虑方法/函数/类的作用,这使你在javadoc中更加具体和清晰,这反过来又让你编写更清晰简洁的代码,这很好.

8> Claudiu..：

---

当我为自己编写代码时 - 没有.在这种情况下,java doccing是浪费我的时间.

当我编写其他人将使用的代码时 - 是的.其他人可以使用的任何方法(任何公共方法)都应该有一个java doc,至少说明它的明显目的.为了一个好的测试 - 在您的代码上运行javadoc创建实用程序(我现在忘记了确切的命令行).浏览它生成的网页.如果您对使用具有该级别文档的库感到满意,那么您就是金色的.如果没有,请在代码中写入更多javadoc.

---

我不同意,我实际上发现,当我6个月后回到项目时,评论通常会节省我的时间和精力.