Java 代码注释最佳实践

Question

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

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

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

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

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

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

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

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

提前致谢...！！！

Answer 1

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

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

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

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