Java代码评论最佳实践

Question

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

我需要遵循最好的行业标准，如果其他人需要修改，那么它应该是明星前进。

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

1. 单行注释（//.....)
2. 阻止评论（/ * ....... * /）
3. 文件评论（/ ** ....... * /）

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

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

想知道块评论中的最佳做法是什么，表示＆＃34;返回＆＃34;类型，＆＃34;参数＆＃34;和＆＃34; breif描述＆＃34;方法或类。

希望听到java代码评论的最佳行业标准做法。

提前致谢... !!!

Answer 1

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

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

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

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

Answer 2

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

有关代码内部的解释，请使用//

要评论几个代码行，请使用/ * ... * /

Answer 3

将Javadoc标准与javadoc tag conventions（第3个选项）一起使用。原因：

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

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