Question

您的评论最佳做法是什么？什么时候应该使用它们应该包含什么？或者甚至需要评论？

Answer 1

评论对于可维护性至关重要。最重要的一点是要解释为什么你在做什么，而不是 WHAT 。

Answer 2

在学校，规则是评论所有内容，以至于评论超过了代码。我认为这很愚蠢。

我认为评论应该用于记录代码背后的“为什么”，而不是“如何”......代码本身解释了“如何”。如果有一项操作不清楚为什么要这样做，那么这是一个评论的好地方。

TODO和FIXME有时会发表评论，但理想情况下，他们应该使用您的源代码管理和错误跟踪工具。

我不介意看似无用的注释的一个例外是文档生成器，它只会打印被注释函数的文档 - 在这种情况下，每个公共类和API接口都需要至少评论到获取生成的文档。

Answer 3

理想情况下，您的程序可以在代码中与读者进行通信，而不是在评论中进行。在我看来，编写其他程序员可以快速理解的软件的能力将最好的程序员与平均程序员区分开来。通常情况下，如果您或您的同事无法理解没有评论的代码段，那么这就是“代码味道”，重构应该是有序的。但是，有一些古老的库或其他集成，一些评论指导普通开发人员不一定是坏的。

Answer 4

通常答案是：它取决于。如果评论好或坏，我认为你写评论的原因对决定非常重要。评论有多种可能的原因：

使结构更清晰（即哪个循环在这里结束）

糟糕：这看起来像是一种可能的代码味道。为什么代码如此复杂，需要注释来清除它？

解释代码的作用

非常糟糕：这在我看来很危险。通常它会发生，您以后更改代码并忘记评论。现在评论是错误的。这非常糟糕。

表示解决方法/修正错误

好：有时问题的解决方案似乎很明确，但简单方法存在问题。如果您解决了问题，添加注释可能会有所帮助，为什么选择此方法。否则，另一个程序员以后可以认为，他“优化”代码并重新引入错误。想想Debian OpenSSL问题。 Debian开发人员删除了一个整数变量。通常，单元化变量是一个问题，在这种情况下，随机性需要它。代码评论有助于澄清这一点。

用于文档目的

好：某些文档可以从特殊格式的注释（即Javadoc）生成。记录公共API是有帮助的，这是必须的。重要的是要记住，文档包含代码的意图，而不是实现。所以回答评论问题'为什么你需要这个方法（以及你如何使用它）'或者该方法是什么？

Answer 5

我认为删除评论的新动作很糟糕......原因是，有很多程序员认为他们编写的代码很容易理解不需要评论的代码。但实际情况并非如此。

你阅读并立即理解其他人的代码有多大百分比..也许我读过太多经典的asp，Perl和C ++，但我阅读的大部分内容都很难撇去。

你有没有读过某人的代码，并对它完全感到困惑。你认为他们在写作的时候会想，这是垃圾，但我并不在乎。他们可能认为哦......这非常聪明，而且 SUPER 很快。

Answer 6

只是一些评论：

评论对于从代码中无法轻易推断的所有内容都很重要（例如复杂的数学算法）。

评论的问题是，它们需要像代码一样进行维护，但通常根本不进行维护。

我不喜欢这样的评论：

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

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

Answer 7

我认为这取决于情景。

方法/函数/类需要简要描述它们的作用，它们是如何做的，它们采取什么以及它们返回的内容，如果不是立即显而易见的，并且通常（在我的代码中）以javadoc的形式出现 - 风格评论块。

在块代码中，我倾向于在一行代码上面留下注释来解释它的作用，或者如果它是一个简短而神秘的函数调用则在行尾添加一个注释。

Answer 8

使用标签搜索，您会发现SO已经有很多关于代码注释的讨论：

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

Commenting code

Answer 9

看看Code Complete。它最适合这些主题。

你觉得怎么样？

9 个答案: