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

Do you use Javadoc for every method you write?

提问by mawaldne

Should I be writing Doc Comments for all of my java methods?

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

采纳答案by VonC

@Claudiu

@克劳迪乌

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.

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

@Daniel Spiewak

@丹尼尔斯皮瓦克

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.

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

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

@Paul de Vrieze

@保罗德弗里兹

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter

对于诸如琐碎的 getter 和 setter 之类的东西，请在 then 之间共享注释并描述属性的用途，而不是 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;
}

And yes, this is more work.

是的，这是更多的工作。

@VonC

@VonC

When you break a huge complex method (because of high cyclomatic complexityreason) into:

当您将一个巨大的复杂方法（由于高圈复杂性原因）分解为：

• one public method calling
• several private methods which represent internal steps of the public one

• 一种公共方法调用
• 代表公共方法的内部步骤的几种私有方法

, it is very useful to javadoc the private methods as well, even though that documentation will not be visible in the javadoc API files.
Still, it allows you to remember more easily the precise nature of the different steps of your complex algorithm.

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

And remember: limit values or boundary conditionsshould be part of your javadoc as well.

请记住：极限值或边界条件也应该是您的 javadoc 的一部分。

Plus, javadoc is way better than simple "//comment":

另外，javadoc 比简单的 "//comment" 好得多：

• It is recognized by IDE and used to display a pop-up when you move your cursor on top of one of your - javadoc-ed - function. For instance, a constant- that is private static final variable -, should have a javadoc, especially when its value is not trivial. Case in point: regexp(its javadoc should includes the regexp in its non-escaped form, what is purpose is and a literal example matched by the regexp)
• It can be parsed by external tools (like xdoclet)

• 它被 IDE 识别并用于在您将光标移动到您的 - javadoc-ed - 功能之一的顶部时显示一个弹出窗口。例如，一个常量- 即私有静态最终变量 - 应该有一个 javadoc，尤其是当它的值不重要时。举个例子：regexp（它的javadoc应该包含非转义形式的regexp，目的是什么以及一个与regexp匹配的文字示例）
• 它可以被外部工具解析（如xdoclet）

@Domci

@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.

对我来说，是否有人会看到它并不重要 - 我不太可能在几个月后知道我编写的一些晦涩的代码段做了什么。[...]
简而言之，注释逻辑，而不是语法，并且只在适当的地方做一次。

@Miguel Ping

@米格尔平

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.

为了评论某事，您必须先了解它。当你试图注释一个函数时，你实际上是在考虑方法/函数/类是做什么的，这让你在你的 javadoc 中更加具体和清晰，这反过来又让你写出更清晰简洁的代码，这很好.

回答by Daniel Spiewak

I thoroughlydocument 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.

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

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.

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

回答by tunaranch

If the method is, obviously self evident, I might skip a javadoc comment.

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

Comments like

评论喜欢

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

Really aren't that useful. (Overly simplistic example, but you get the idea)

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

回答by Marcus Tik

simply put: YES

简单地说：是的

The time you need to think about whether you should write a doc, is better invested in writing a doc.

您需要考虑是否应该编写文档的时间，最好投资于编写文档。

Writing a one-liner is better than spending time for not documenting the method at all in the end.

写一个单行代码比花时间最后根本不记录方法要好。

回答by anjanb

at a previous company, we used to use the jalopy code formatter with eclipse. That would add javadoc to all the methods including private.

在以前的一家公司，我们曾经在 Eclipse 中使用老爷车代码格式化程序。这会将 javadoc 添加到包括私有在内的所有方法中。

It made life difficult to document setters and getters. But what the heck. You have to do it -- you do it. That made me learn some macro functionality with XEmacs :-) You can automate it even further by writing a java parser and commenter like ANTLR creator did several years ago :-)

记录 setter 和 getter 变得很困难。但是这到底是怎么回事。你必须这样做——你必须这样做。这让我学习了一些 XEmacs 的宏功能:-) 你可以通过编写一个 java 解析器和评论器来进一步自动化它，就像几年前 ANTLR 创建者所做的一样 :-)

currently, I document all public methods and anything more than 10 lines.

目前，我记录了所有公共方法和超过 10 行的任何内容。

回答by Claudiu

When I write code for myself - NO. In this case, java doccing is a waste of my time.

当我为自己编写代码时 -不。在这种情况下，java docing 是在浪费我的时间。

When I write code that others will use - Yes. Every method that somebody else can use (any public method) should have a java doc at least stating its obvious purpose. For a good test - run the javadoc creation utility on your code (I forget the exact command line now). Browse through the webpage it generates. If you would be satisfied using a library with that level of documentation, you're golden. If not, Write more javadocs in your code.

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

回答by Nrj

I feel there should at least be comments regarding the parameters accepted and return types in term of what they are.
One can skip the implementation details in case the function names describes it completely, for eg, sendEmail(..);

我觉得至少应该有关于接受的参数和返回类型的评论。
如果函数名称完全描述了它，则可以跳过实现细节，例如，sendEmail(..)；

回答by Paul de Vrieze

For things, like trivial getters and setters, share the comment between then and describe the purpose of the property, not of the getter/setter.

对于诸如琐碎的 getter 和 setter 之类的事情，请在两者之间共享注释并描述属性的用途，而不是 getter/setter 的用途。

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

Is not useful. Better do something like:

是没有用的。最好做一些类似的事情：

/** 
 * 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;
}

And yes, this is more work.

是的，这是更多的工作。

回答by volley

All bases covered by others already; one additional note:

其他人已经涵盖的所有基地；补充说明：

If you find yourself doing this:

如果你发现自己这样做：

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

Consider changing it into this:

考虑把它改成这样：

void launchBlaardhIntoBleeyrg() { ... }

This may seem a bit obvious, but in many cases the opportunity is easy to miss in your own code.

这可能看起来有点明显，但在许多情况下，您自己的代码很容易错过这个机会。

Finally keep in mind that the change is not alwayswanted; for instance the behaviour of the method may be expected to evolve over time (note the word "currently" in the JavaDoc).

最后请记住，并非总是需要更改；例如，该方法的行为可能会随着时间的推移而演变（注意 JavaDoc 中的“当前”一词）。

回答by CodingWithSpike

I try to at the very least document every public and interface property and method, so that people calling into my code know what things are. I also try to comment as much as possible in line as well for maintenance sake. Even 'personal' projects I do on my own time just for myself, I try to javadoc just because I might shelf it for a year and come back to it later.

我尝试至少记录每个公共和接口属性和方法，以便调用我的代码的人知道什么是东西。为了维护起见，我也尝试尽可能多地发表评论。即使是我在空闲时间为自己做的“个人”项目，我也会尝试使用 javadoc，因为我可能会将它搁置一年，然后再回来使用。