我们发表评论的最佳做法是什么？什么时候应该使用它们，以及它们应该包含什么？还是需要评论？

解决方案

注释对于可维护性至关重要。要记住的最重要一点是要解释为什么要做某事，而不是正在做什么。

我认为这取决于情况。

方法/函数/类需要简短描述它们的工作，如何做，采取什么以及它们返回什么(如果不是很明显的话)，并且通常(在我的代码中)以javadoc样式的注释块的形式出现。

在块内代码中，我倾向于在一行代码的上方留下注释，以解释其功能；如果是简短而神秘的函数调用，则在行末添加一个注释。

在学校里，规则是注释所有内容，以至于注释超出代码。我认为这很愚蠢。

我认为应该使用注释来记录代码背后的"为什么"，而不是"如何" ...代码本身解释了"如何"。如果某项操作不清楚执行的原因，那么可以在此发表评论。

有时会在注释中加入TODO和FIXME，但理想情况下，它们应该加入源代码管理和错误跟踪工具中。

我不介意看似无用的注释的一个例外是文档生成器，该文档生成器仅会打印在这种情况下已注释的函数的文档，每个公共类和API接口至少需要注释一下才能生成文档。

使用标签搜索，我们会发现SO已经有大量关于代码注释的讨论：

https://stackoverflow.com/questions/tagged/comments

注释码

理想情况下，程序可以用代码而不是注释与读者交流。在我看来，其他程序员可以快速理解的编写软件的能力将优秀的程序员与普通的程序员区分开了。通常，如果我们或者同事在没有注释的情况下无法理解一段代码，则这是"代码异味"，因此应该进行重构。但是，有些古老的库或者其他集成对于一些指导普通开发人员的评论并不一定是不好的。

答案通常是：取决于情况。我认为我们写评论的原因对决定非常重要，无论评论的好坏。发表评论的原因可能有多种：

• 使结构更清晰(即哪个循环在此处结束)

不好：这看起来像是可能的代码气味。为什么代码如此复杂，需要注释才能清除？

• 解释一下，代码做什么

非常糟糕：我认为这很危险。通常，我们以后更改代码而忘了注释会经常发生。现在，评论是错误的。这真是太糟了。

• 指示解决方法/错误修正

好：有时​​候解决问题的方法似乎很明确，但是简单的方法却有问题。如果我们解决了该问题，则添加注释可能会有所帮助，为什么选择这种方法。否则，另一个程序员以后会想到，他"优化"了代码并重新引入了错误。考虑一下Debian OpenSSL问题。 Debian开发人员删除了一个统一变量。通常，一个统一变量是一个问题，在这种情况下，它是随机性所必需的。代码注释将有助于清除该问题。

• 用于文档目的

良好：可以从特殊格式的注释(例如Javadoc)中生成一些文档。记录公共API很有帮助，这是必须具备的。重要的是要记住，文档包含了代码的意图，而不是实现的意图。因此，请回答以下问题："为什么需要该方法(以及如何使用它)"或者该方法是什么？

我认为删除注释的新方法很糟糕……原因是，许多程序员认为他们正在编写不需要注释的易于理解的代码。但实际上并非如此。

我们会阅读并立即理解其他人的代码的比例。也许我读了太多经典的asp，Perl和C ++，但是我读的大多数东西还是很难读懂的。

我们是否曾经读过某人的代码，并完全被它弄糊涂了。我们认为他们在写作时是否认为这是胡扯，但我不在乎。他们可能以为哦。。。这很聪明，将会很快。

看看代码完成。最适合此类主题。

只是一些注意事项：

注释对于无法从代码中轻松推断出的所有内容(例如，复杂的数学算法)都很重要。

注释的问题在于，它们需要像代码一样进行维护，但通常根本不维护。

我不喜欢这样的评论：

// 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 );
}

现在，代码讲述了整个故事。无需评论。