代码评论者宝石

Question

几个月前我确信有一个宝石可以确保您对每一行代码都进行了评论。或至少每一个动作。如果你还没有，那么在你运行某种佣金任务之后就会引起你的注意。

不能记住我的生活是什么。

但是对每一行代码进行评论是一个好主意吗？我说是的，它巩固了你的知识，为你提供了最后一次改变，以捕捉错误/安全漏洞并简化未来的发展。

然而，github中的项目并没有真正稀疏评论。就个人而言，在开始意识到代码片段的作用之前，我需要对大多数行进行评论。大多数情况不是这样吗？评论只是叮嘱ninjas吗？

Answer 1

评论每一行代码都是一个可怕的想法：

1. 它嘈杂并混淆了源
2. 它很容易变得过时

评论事项：

1. 棘手和/或hacky代码
2. 复杂算法
3. 为什么正在做的事情

这些评论几乎总是存在于方法层面。

1. 如果代码块需要注释，则应该是方法
2. 如果一行代码需要注释，则应该重构

代码应该尽可能地说明问题。适当的命名采用 long 方式消除了大量评论的需要。有些文档可能是绝对必要的，但是在大型结构注释的情况下，将它保留在代码之外以及在wiki中可能更有意义。

Answer 2

不，评论每一行代码都不是一个好主意。很多代码都是不言自明的。实际上，您应该努力使代码不言自明。

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

sum = 1 + 3

您应该保存您需要解释的内容的评论。

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

关于您正在考虑的宝石，它可能是rubocop。