java - 您编写的每个方法都使用 Javadoc 吗？

Question

关闭。这个问题是 opinion-based .它目前不接受答案。

---

想要改进这个问题吗？ 更新问题，以便 editing this post 提供事实和引用来回答它.

关闭 4 年前。

Improve this question

我应该为我的所有 java 方法编写文档注释吗？

Answer 1

@克劳迪乌

When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a javadoc at least stating its obvious purpose.

@丹尼尔·斯皮瓦克

I thoroughly document every public method in every API class. Classes which have public members but which are not intended for external consumption are prominently marked in the class javadoc. I also document every protected method in every API class, though to a lesser extent. This goes on the idea that any developer who is extending an API class will already have a fair concept of what's going on.

Finally, I will occasionally document private and package private methods for my own benefit. Any method or field that I think needs some explanation in its usage will receive documentation, regardless of its visibility.

@保罗·德弗里兹

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the 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

当你把一个巨大的复杂方法(因为high cyclomatic complexity的原因)分解成:

• 一个公共(public)方法调用
• 代表公共(public)方法内部步骤的几个私有(private)方法

，javadoc 私有(private)方法也非常有用，即使该文档在 javadoc API 文件中不可见。
尽管如此，它仍然可以让您更轻松地记住复杂算法的不同步骤的精确性质。

记住: limit values or boundary conditions 也应该是您的 javadoc 的一部分。

另外，javadoc 比简单的“//comment”要好得多:

• 它被 IDE 识别并用于在您将光标移动到您的一个 - javadoc-ed - 函数的顶部时显示一个弹出窗口。例如，一个 constant - 即私有(private)静态最终变量 - 应该有一个 javadoc，尤其是当它的值不是微不足道的时候。恰当的例子:regexp(它的 javadoc 应该包含非转义形式的 regexp，目的是什么以及与 regexp 匹配的文字示例)
• 可以被外部工具解析(如xdoclet)

@Domci

For me, if somebody will see it or not doesn't matter - it's not likely I'll know what some obscure piece of code I wrote does after a couple of months. [...]
In short, comment logic, not syntax, and do it only once, on a proper place.

@米格尔平

In order to comment something, you have to understand it first. When you trying to comment a function, you are actually thinking of what the method/function/class does, and this makes you be more specific and clear in your javadoc, which in turn makes you write more clear and concise code, which is good.