你觉得怎么样？

您的评论最佳做法是什么？什么时候应该使用它们应该包含什么？或者甚至需要评论？

评论对于可维护性至关重要.要记住的最重要的一点是要解释为什么你正在做的事情,没有什么你正在做.

在学校,规则是评论所有内容,以至于评论超过了代码.我觉得这很傻.

我认为评论应该用来记录代码背后的"为什么",而不是"如何"......代码本身解释了"如何".如果有一个操作不清楚它为什么要完成,那么这是一个评论的好地方.

TODO和FIXME有时会发表评论,但理想情况下,它们应该包含在您的源代码管理和错误跟踪工具中.

我不介意看似无用的注释的一个例外是文档生成器,它只会打印被注释函数的文档 - 在这种情况下,每个公共类和API接口都需要至少注释才能获得文档产生.

通常答案是:它取决于.如果评论好或坏,我认为你写评论的原因对决定非常重要.评论有多种可能的原因:

使结构更清晰(即哪个循环在这里结束)

不好:这看起来像是一种可能的代码味道.为什么代码如此复杂,需要注释来清除它？

解释代码的作用

非常糟糕:这在我看来很危险.通常它会发生,您以后更改代码并忘记评论.现在评论是错误的.这真是太糟了.

表示解决方法/修正错误

好:有时问题的解决方案似乎很清楚,但简单的方法有问题.如果您解决了问题,添加注释可能会有所帮助,为什么选择此方法.否则,另一位程序员以后可以认为,他"优化"代码并重新引入错误.想想Debian OpenSSL问题.Debian开发人员删除了一个整数变量.通常,单元化变量是一个问题,在这种情况下,随机性需要它.代码注释有助于澄清这一点.

用于文档目的

好:有些文档可以从特殊格式的注释(即Javadoc)生成.记录公共API是有帮助的,这是必须的.重要的是要记住,文档包含代码的意图,而不是实现.所以回答评论问题'为什么你需要这个方法(以及你如何使用它)'或者该方法是什么？

理想情况下,您的程序可以通过代码而不是注释与读者进行通信.在我看来,编写其他程序员可以快速理解的软件的能力将最好的程序员与平均程序员区分开来.通常情况下,如果您或您的同事无法理解没有评论的代码段,那么这就是"代码味道",重构应该是有序的.但是,有一些古老的库或其他集成,一些评论指导普通开发人员并不一定是坏的.