什么是不同的代码评论做法？

Question

阅读代码评论，似乎普遍支持的评论，不解释代码本身可以解释的任何东西。我查过的所有资源（没有那么多，但仍有一些）说，这些评论应该在更高级别的抽象层次上解释代码。

但是，我在社交和合作领域的专家都支持说，更多的评论总比不够好，即使评论解释了读者/编码人员可以从代码中解读的东西，但是这个层次有不同的层次，有些人可能会比其他人更快地解密代码，所以为了安全起见，最好是评论其意义不明显的代码; “

”当你不必阅读实际的代码，并且可以理解函数在英文中做什么，而不是尝试和解密代码时，它将帮助你作为一个编码器，有时候，它甚至可能有助于在编写代码之前在注释和伪代码中编写函数;它将有助于不断提醒此功能假设要做什么。“

就评论而言，这两者是完全不同的思想流派。这引出了一个问题：

什么是关于代码注释思想不同的学校，什么是最流行的（从而避免询问有关最好的，因为这是主观的）来源，我可以读了关于代码评论的做法？

Answer 1

这是一个非常清晰的文字，名为The Fine Art of Commenting而非ic＃代码。这并不完美（匈牙利符号很可怕，不应该在开发者身上造成），但它仍然相当有趣。

作者正确地指出，有可能要使用征求意见不同的东西，并把它们分成3类：

• 纪录片的意见，例如版权信息，作者和版本和变化的信息。
• 功能注释，这是您的各种“TODO”和“BUG”注释，指出可能需要进一步关注的代码区域。
• 解释性意见，它解释了代码的作用。

第三类显然是这里讨论的有趣之一。在我看来，评论应该描述代码为什么会这样做，而不是如何。例如，如果您的代码对列表进行排序，您应该解释为什么列表必须首先排序 - 列表正在排序（或应该）从代码中显而易见。

最后，关于注释最重要的是它们没有被编译，并且对程序的行为没有影响。这看起来很明显。这样做的结果是，在软件的维护阶段，代码中的错误可能是固定的，但注释通常保持不变，并且可以记录不再被观察到的行为。由于错误文档比不存在的文档更没有用处，修复注释中的错误以及实际代码非常重要。