有哪些不同的代码注释做法？

Question

阅读代码注释，似乎普遍支持不解释代码本身可以解释的任何内容的 cmets。我查过的所有来源（不是很多，但仍然有一些）说 cmets 应该在更高的抽象层次上解释代码。

但是，与我交往和工作的领域的专家都支持更多的 cmets 总比不够好，即使 cmets 解释了读者/编码人员可以从代码中破译的东西，这也有不同的层次，有些人可能比其他人更快地破译代码，所以为了安全起见，最好注释掉意义不明显的代码；毕竟，

“作为一名程序员，当你不必阅读实际代码时，它会帮助你，并且可以理解一个函数在英语中的作用，而不是尝试和破译代码。有时，它甚至可能有助于编写在对其进行编码之前，在 cmets 和伪代码中输出函数；这将有助于不断提醒该函数应该做什么。”

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

关于代码注释有哪些不同的思想流派，哪些是我可以阅读的最流行的（以避免询问最好的，因为那是主观的）来源了解代码注释做法？

Answer 1

这是一篇相当犀利的文章，名为The Fine Art of Commenting，位于 ic#code。它并不完美（匈牙利符号很糟糕，不应该强加给开发人员），但它仍然相当有趣。

作者正确地指出，您可能希望使用 cmets 完成不同的事情，并将它们分为 3 个类：

• 文献资料，例如版权信息、作者身份、版本和更改信息。
• 功能性 cmets，它们是您的各种“TODO”和“BUG” cmets，指示可能需要进一步关注的代码区域。
• 解释性 cmets，解释代码的作用。

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

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