您对 cmets 的最佳做法是什么？什么时候应该使用它们，它们应该包含什么？还是需要 cmets？
【问题讨论】：
标签： comments
注释对于可维护性至关重要。要记住的最重要的一点是解释为什么你在做某事，而不是WHAT你在做什么。
【讨论】：
在学校，规则是评论所有内容，以至于 cmets 胜过代码。我认为这很愚蠢。
我认为 cmets 应该用于记录代码背后的“为什么”，而不是“如何”……代码本身解释了“如何”。如果有一个操作并不清楚为什么要完成，这是一个发表评论的好地方。
TODO 和 FIXME 有时会出现在 cmets 中，但理想情况下它们应该出现在您的源代码管理和错误跟踪工具中。
我不介意看似无用的 cmets 的一个例外是文档生成器，它只会打印已注释函数的文档 - 在这种情况下，每个公共类和 API 接口都需要至少注释到足以获取生成的文档。
【讨论】：
答案通常是：视情况而定。我认为您写评论的原因对于决定是好是坏非常重要。 cmets有多种可能的原因：
不好：这看起来可能是代码异味。为什么代码如此复杂，需要注释来清除？
非常糟糕：我认为这很危险。通常会发生，您稍后更改代码并忘记注释。现在评论是错误的。这很糟糕。
好：有时问题的解决方案看起来很清楚，但简单的方法有问题。如果您解决了问题，添加评论可能会有所帮助，说明选择此方法的原因。否则，稍后的另一个程序员可能会认为，他“优化”了代码并重新引入了错误。想想 Debian OpenSSL 问题。 Debian 开发人员删除了一个未初始化的变量。通常一个统一变量是一个问题，在这种情况下它是随机性所需要的。代码注释将有助于澄清这一点。
好：可以从特殊格式的 cmets（即 Javadoc）生成一些文档。记录公共 API 很有帮助，这是必不可少的。重要的是要记住，文档包含代码的意图，而不是实现。因此，请回答“为什么需要该方法（以及如何使用它）”或该方法有什么作用？
【讨论】：
理想情况下，您的程序可以通过代码而不是 cmets 与阅读器进行通信。在我看来，编写其他程序员可以快速理解的软件的能力将最好的程序员与平均水平区分开来。通常，如果您或您的同事在没有 cmets 的情况下无法理解一段代码，那么这是一种“代码异味”，应该按顺序进行重构。不过会有一些陈旧的库或者其他集成，少数cmets来指导普通开发者未必不好。
【讨论】：
我认为删除 cmets 的新运动很糟糕……原因是，有很多程序员认为他们正在编写易于理解的代码，而不需要 cmets。但实际上并非如此。
你阅读了多少其他人的代码并立即理解它。也许我阅读了太多经典的 asp、Perl 和 C++，但我阅读的大多数内容都很难略读。
您是否曾经阅读过某人的代码，并被它完全弄糊涂了。你认为他们在写作时会想，这是废话，但我并不在乎。他们可能认为哦……这非常聪明，而且速度会SUPER。
【讨论】：
只是一些评论：
对于无法从代码中轻易推断出的所有内容（例如复杂的数学算法），注释都很重要。
cmets 的问题在于，它们需要像代码一样维护，但通常根本不维护。
我不喜欢这样的cmets：
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
更好：
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
现在代码说明了整个故事。无需评论。
【讨论】：
我认为这取决于场景。
方法/函数/类需要简短描述它们的作用、它们是如何做的、它们采用什么以及它们返回什么，如果不是很明显并且通常（在我的代码中）以 javadoc 的形式出现 -样式注释块。
块内代码，我倾向于在一行块上方留下注释来解释它的作用，或者如果它是一个简短而神秘的函数调用，则在行尾留下注释。
【讨论】：
使用标签搜索，您会发现 SO 已经有大量关于代码 cmets 的讨论：
【讨论】：
看看Code Complete。它最适合此类主题。
【讨论】：