代码注释创业板

Question

几个月前，我确信有一个创业板，它确保您已经注释了每一行代码。或者至少是每一个动作。如果你没有这样做，它会在你执行某种耙式任务后引起你的注意。

我不记得它叫什么了。

，但是对每一行代码进行注释是个好主意吗?我说是的，它巩固了您的知识，给了您最后一次更改以捕获bug/安全漏洞，并简化了未来的开发。

然而，在github的项目和真的很少评论。就我个人而言，在我开始意识到一段代码做什么之前，我需要对大多数行进行评论。对大多数人来说不是这样吗？评论只是把代码忍者绊倒了吗？

Answer 1

注释每一行代码都是一个可怕的想法：

1. 它很吵，把源弄糊涂了
2. 很容易就过时了

需要评论的事情：

1. 棘手的代码和/或黑客代码
2. 复杂算法
3. 为什么有些东西在做它正在做的事

这些注释几乎应该始终保持在方法级别。

1. 如果一个代码块需要注释，它可能是一个方法。
2. 如果一行代码需要注释，则可能需要重构。

代码应该尽可能多地为自己说话。适当的命名可以很大程度上消除评论的需要。某些文档可能是绝对必要的，但对于大型结构注释，将其排除在代码之外和您的wiki中可能更有意义。

Answer 2

不，对每一行代码进行注释并不是个好主意。很多代码是不言自明的。实际上，您应该努力使代码变得不言自明。

例如，您永远不会想要评论以下内容：

sum = 1 + 3

你应该把你的评论留给那些需要解释的事情。

我认为你的意思是一个宝石，执行适当的文件。文档是一种注释，它解释方法或类的用途，并详细说明其参数和返回值。

关于你正在考虑的宝石，它可能是鲁博克。