Java代码注释最佳实践

Question

我已经完成了我的Java/Android项目，现在我需要对代码(主要是类和重要方法)进行评论。

我需要遵循最好的工业标准，就像以后有人需要修改一样，它应该是正确的。

我阅读了许多文章，发现了3种主要类型的java注释样式。

1. 单行注释(//.)
2. 块注释(/* .*/)
3. 医生评论(/** .*/)

我主要读到的是选项2和3. 堆栈溢出讨论

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

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

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

谢谢.！！

Answer 1

我建议使用第三个选项，因为如果有人查看您的代码--例如，通过一个支持JavaDOC的IDE (例如Eclipse) --当他/她在感兴趣的元素上徘徊时，它将显示有关他/她检查的对象的相关信息。

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

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

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

Answer 2

有关API的说明，请使用javadoc /** . */

有关代码内部的说明，请使用//

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

Answer 3

使用Javadoc标准和javadoc 标签约定 (第三个选项)。为什么：

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

第一个和第二个选项更适合直接在代码行上进行注释。不是用来描述类和方法的。