Java 代码注释最佳实践答案

【问题标题】：Java code commenting best practicesJava 代码注释最佳实践
【发布时间】：2014-05-15 05:07:46
【问题描述】：

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

我需要按照最好的行业标准来做，以后如果其他人需要修改，应该很好。

我阅读了很多文章，发现了 3 种主要的 java 评论风格。

单行注释 (//.....)
块 cmets (/* ....... */)
Doc cmets (/** ....... */)

我主要阅读了选项 2 和 3。Stack overflow discussions

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

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

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

提前谢谢...！！！

【问题讨论】：

这不是重复的，因为我在问我的问题中选择选项 2 的最佳工业方法....基本上如果一个方法有几个参数如何解释每个参数（比如@参数在 doc cmets 中有）。还有返回类型等......
很公平，评论已删除。

标签： java android comments

【解决方案1】：

使用 Javadoc 标准和 javadoc tag conventions（第三个选项）。为什么：

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

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

【讨论】：

【解决方案2】：

我建议使用第 3 个选项，因为如果有人通过支持 JavaDOC（例如 Eclipse）的 IDE（例如 Eclipse）查看您的代码，当他/她检查时，它将显示有关他/她检查的对象的相关信息将鼠标悬停在他/她感兴趣的元素上。

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

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

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

【讨论】：

感谢天花板壁虎。很好的解释。但就我而言，大多数类和方法永远不需要生成 HTML 文档。大多数代码都是特定于这个应用程序的，根本不使用 HTML 文档......这就是为什么我希望使用选项 2 以及解释参数和返回类型的正确方法，因为选项 3 具有（@param，@return ）。谢谢。
重点是您询问了行业标准。您的开发人员同事会告诉您除了您自己之外的其他人将如何查看源代码。另一种方法是查看有 cmets 遵循其实践的实际开源项目。 Doc 样式绝对是描述代码块的首选方式，而线条样式最适合这些块中的单个项目。

【解决方案3】：

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

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

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

【讨论】：

感谢 Pavel Bernshtam。是的，正如你所说，我需要几行注释选项，主要是因为它不会是一个 API。而且这些类和方法是这个应用程序特定的，不会被任何 3rd 方应用程序使用......我正在寻找的是完全描述方法的最佳方式。例如在 doc cmets 中它有（@param、@return 等）。使用块 cmets (/* sevela lines */) 的方法....