Java源文件中注释的最佳实践?

我听说的一件合乎逻辑的事情是把作者排除在标题之外,因为标题是多余的

最后修改日期也是 冗余的

:

• 始终记录不变性
• javadoc及其示例
• @弃用 为什么 和
• 尽量减少评论

“最后修改日期”也属于源代码管理。

实现注释通常应该是关于你为什么做一些不明显的事情,因此应该很少。(例如,这可能是因为某些API的行为方式不同寻常,或者因为有一个有用的快捷方式可以使用,但并不明显。)

为了你自己和未来开发人员的理智,你真的应该写 Javadocs .

当你觉得需要写注释来解释某些代码的功能时,提高代码的可读性,这样就不需要注释了。你可以通过重命名方法/字段/类来获得更多信息 meaningful names ,并使用 composed method pattern .

如果即使经过你的努力,代码也不是不言自明的,例如原因 为什么 必须编写一些不明显的代码,从代码中看不清楚,那么 apologize by writing comments (有时你可以通过编写一个测试来记录失败的原因,如果有人更改了不明显但正确的代码来做明显但错误的事情。但除此之外还有一个注释也是有用的。我经常在这样的注释前加上“//HACK:”或“//XXX:”。)

类目的的总体描述、每个字段的描述和每个方法的契约。Javadoc格式运行良好。