关于代码中的评论

如果我写了自我记录代码，我曾经认为我不需要评论。但是，我已经意识到我做评论，我发现它们真的很有用。要查看我写的评论，以及他们是什么样的，我写了一个脚本来分析过去六年的Git提交。总共有7％的承诺行包含了评论。此博客文章有关于什么构成好的和坏评论的详细信息，以及我脚本的更多统计数据。

我对评论持怀疑态度的一部分是javadoc风格评论的普遍性。这种评论风格也存在于其他语言中。这是我刚刚组成的Python中的一个例子，但这是这种风格的代表：

大多数这些评论的问题是它们传达了很少的信息。通常，它只是重复了一些单词的方法名称和参数名称。这些评论可能对API有用：S外部暴露，但在您可以访问所有源代码的应用程序中，它们大多是无用的。如果您想知道该方法所做的，或者参数的有效输入范围是什么，您只需阅读代码即可查看它所的代码。这些类型的评论占用了很多空间而不提供大量价值。

您可以更好地使用方法名称和变量名称，而不是编写Javadoc评论，而不是编写Javadoc评论。您使用的每个名称都可以帮助解释计算是什么以及它的完成方式。写出许多小方法而不是一个大型方法的一个好理由是您有更多的地方使用描述性名称，我写的东西。

编写自我记录代码会让您获得很长的路要走。但是，有更多信息时的时间很有用。例如，关于在下面的代码中使用拨号区域的注释：

经常给出的建议是“评论为什么，而不是什么”。虽然这可能涵盖了大部分评论，但这不是我如何考虑何时发表评论。相反，当在域中或如何完成实现时，我倾向于在何时存在特别棘手。

“无注释所需的”标准建议--CROWD（我曾经属于哪种）是重写代码，以便您不需要发表评论。然而，这并不总是可能的。有时域名太复杂。有时重写代码的努力将与添加评论进行比较太多。

另一个关于评论的投诉是，他们将与代码失去同步，从而阻碍了对代码的理解而不是帮助它。虽然这有时会发生这种情况，但它对我来说并不是一个大问题。在几乎所有分析的情况下，评论仍然有效。他们也非常有用。每当我遇到我这样的评论之一时，我很高兴我写了它。忘记您正在解决的问题的一些细节和细微差别并不需要很长时间，并在那里有一些额外的背景和解释的评论很大。

有时，如果您正在记录解释性消息，您会收到评论“免费”。在下面的示例中，日志语句解释了发生了什么，因此无需注释。

当我第一次考虑检查所有提交的评论时，我认为这将足够了，一个衬里这样的单行可以在我的所有Python提交中找到评论（我只使用＃的评论）：

但是，我很快意识到我想要更多细节。我想区分线尾注释和整个线条评论。我也想了解我有多少“评论块”（连续评论线）。我还决定从分析中排除测试文件。此外，我希望一定要排除发生在那里的任何注释的代码（遗憾的是，这样的这种情况）。最后我写了一个python脚本来进行分析。脚本的输入是Git Log --Author = Henrik -P的输出。

从输出中，我看到的，在17817年中，矿的1299分中含有的评论。有161个终端的评论，464个单行评论。最长的评论块是11行，并且有96个评论块有3个或更多连续行。

我曾经认为写出命名优势的函数意味着没有必要的评论。然而，看着我实际所做的事情，我注意到我倾向于在代码的棘手或不完整的部分中添加评论。每次我回到该计划的那些部分时，我很高兴我努力添加评论 - 他们一直很有帮助！