你是否在你编写的每个方法中使用Javadoc？[已关闭]

@Claudiu

当我编写其他人将使用的代码时 - 是的。其他人可以使用的每个方法（任何公共方法）都应该有一个javadoc，至少说明其明显的目的。

@Daniel斯皮瓦克

我彻底记录了每个API类中的每个公共方法。具有公共成员但不供外部使用的类在 javadoc 类中突出显示。我还记录了每个API类中的每个受保护方法，尽管程度较小。这延续了这样一种观点，即任何正在扩展API类的开发人员都已经对正在发生的事情有了一个公平的概念。

最后，为了我自己的利益，我偶尔会记录私有和打包私有方法。我认为需要对其用法进行一些解释的任何方法或字段都将收到文档，无论其可见性如何。

@Paul德弗里兹

对于事物，如琐碎的 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，特别是当它的值不是微不足道的时候。举个例子：正则表达式（它的javadoc应该包括其非转义形式的正则表达式，目的是什么，以及与正则表达式匹配的文字示例）
• 它可以通过外部工具（如xdoclet）解析)

@Domci

对我来说，如果有人看到它并不重要 - 几个月后我不太可能知道我写的一些晦涩难懂的代码是做什么的。[...]
简而言之，注释逻辑，而不是语法，并且只在适当的位置执行一次。

@Miguel平

为了评论某些东西，你必须首先理解它。当你尝试注释一个函数时，你实际上是在考虑方法/函数/类的作用，这使你在javadoc中更加具体和清晰，这反过来又使你写得更清晰简洁，这很好。

如果该方法显然是不言而喻的，我可能会跳过javadoc注释。

评论喜欢

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

真的没那么有用。（过于简单的例子，但你明白了）