Java 代码注释最佳实践

Java code commenting best practices

提问by JibW

I have finalized my Java/Android project and now I need to comment the codes (mainly classes and important methods).

我已经完成了我的 Java/Android 项目，现在我需要注释代码（主要是类和重要方法）。

I need to do it by following the best industrial standards as later if someone else need to modify, it should be well staright forward.

我需要按照最好的行业标准来做，因为以后如果其他人需要修改，它应该是正确的。

I read many articles and found 3 main types of java commenting styles.

我阅读了很多文章，发现了 3 种主要的 Java 注释样式。

1. Single line comment (//.....)
2. Block comments (/* ....... */)
3. Doc comments (/** ....... */)

1. 单行注释 (//.....)
2. 块注释 (/* ....... */)
3. 文档注释 (/** ....... */)

I read mainly about the option 2 and 3. Stack overflow discussions

我主要阅读选项 2 和 3。堆栈溢出讨论

So I thought of going with 2nd option as I don't need to generate HTML docs as these classes are not going to use by any other people and this is the implementation of this app.

所以我想使用第二个选项，因为我不需要生成 HTML 文档，因为这些类不会被任何其他人使用，这就是这个应用程序的实现。

Wonder what are the best practices in block commenting indicating "return" type, "parameters" and "breif description" of the method or class.

想知道在块注释中指示方法或类的“返回”类型、“参数”和“简短描述”的最佳实践是什么。

Would like to hear the best industrial standard practices of the java code commenting.

想听听 java 代码注释的最佳工业标准实践。

Thanks in advance...!!!

提前致谢...！！！

回答by Ceiling Gecko

I would recommend going with the 3rd option, because if someone looks at your code for example through an IDE which supports the JavaDOCs (e.g. Eclipse), it'll show relevant information about the objects he/she examines when he/she hovers over an element that interests him/her.

我建议使用第三个选项，因为如果有人通过支持 JavaDOC（例如 Eclipse）的 IDE 查看您的代码，当他/她将鼠标悬停在他/她感兴趣的元素。

This way, the developer will not have to open the actual class source file to understand what it's contract is, what does it do, or perhaps what Exceptions you have to lookout for when using it.

这样，开发人员就不必打开实际的类源文件来了解它的契约是什么，它做了什么，或者在使用它时可能需要注意哪些异常。

You can link relevant classes/methods together via JavaDOC hooks like @see.

您可以通过像@see 这样的 JavaDOC 钩子将相关的类/方法链接在一起。

Personally, I usually like to put DOC comments at least on my class, and public methods, for private methods I don't usually see much use for DOC comments since I don't usually generate the JavaDOC HTML. Other than DOC comments I usually tend to use the single line comments, and only use block comments when I feel like 1 sentence will not be enough to express what I wanted to, or when the print margin restrictions come into play.

就我个人而言，我通常喜欢至少在我的类和公共方法上放置 DOC 注释，对于私有方法，我通常看不到 DOC 注释有多大用处，因为我通常不生成 JavaDOC HTML。除了 DOC 注释，我通常倾向于使用单行注释，并且仅在我觉得 1 句话不足以表达我想要的内容或打印边距限制发挥作用时才使用块注释。

回答by Pavel Bernshtam

For explanation about API use javadoc /** ... */

关于 API 的解释使用 javadoc /** ... */

For explanations inside code use //

对于代码内部的解释，请使用 //

For commenting out several code lines use /* ... */

要注释掉几行代码，请使用 /* ... */

回答by VinZ

Use the Javadocstandard with the javadoc tag conventions(3rd option). Why:

将Javadoc标准与 javadoc标记约定（第三个选项）结合使用。为什么：

• It is a widly used standard that every java progammer should easy understand.
• Most IDEs support the javadoc standard and tags. The IDE show relevant information and helps developer
• If you don't need to generate HTML now, maybe you need to do it later.
• It is the "industrial standard", as you ask for.
• By describing classes and methods, you describe the API of you programm. The standard for describing the API is Javadoc, so use it.

• 这是一个广泛使用的标准，每个 Java 程序员都应该很容易理解。
• 大多数 IDE 支持 javadoc 标准和标签。IDE 显示相关信息并帮助开发者
• 如果您现在不需要生成 HTML，也许您需要稍后再生成。
• 正如您所要求的，它是“行业标准”。
• 通过描述类和方法，你描述了你的程序的 API。描述 API 的标准是 Javadoc，所以使用它。

The first and second option is more for comments directly on code lines. Not for description of the classes and methods.

第一个和第二个选项更多用于直接在代码行上的注释。不用于描述类和方法。