Question

我总是讨厌用星号填充屏幕一半的评论只是为了告诉你函数返回一个字符串，我从来没有读过那些评论。

但是，我确实阅读了一些评论，这些评论描述了为什么要做的事情以及它是如何完成的（通常是代码中的单行注释）;那些在试图理解别人的代码时非常方便。

但是当谈到写评论时，我不写那个，相反，我只是在编程竞赛中编写算法时使用注释，我会想到算法将如何做它然后我写的每个注释中的一个，然后编写与该注释对应的代码。

一个例子是：

//loop though all the names from n to j - 1

除此之外，我无法想象为什么有人会在撰写评论时浪费宝贵的时间撰写评论。

我是对还是错？我错过了什么吗？我不知道其他哪些好的评论用例？

Answer 1

评论应该表达为什么你做的不是你正在做的事情

Answer 2

这是一句古老的格言，但使用的一个好指标是：

评论为什么你正在做某事，而不是你在做什么。

说“从n到j-1循环遍历所有名称”应该立即对单独的代码中的新手程序员清楚。给出你这样做的原因有助于提高可读性。

Answer 3

如果您使用类似Doxygen的内容，则可以完整记录返回类型，参数等，并生成一个很好的“源代码手册”。我经常为客户这样做，以便继承我的代码的团队不会完全丢失（或被迫审查每个标题）。

文档块通常过度，特别是强类型语言。使用Python或PHP之类的东西比使用C ++或Java更加冗长。也就是说，对于方法和方法来说，它仍然很好。不自我解释的成员（例如，未命名更新）。

我已经花了很多时间思考，只是通过评论我第一次阅读我的代码时想要告诉自己的内容。更多的叙述和更少的观察。评论不仅应该帮助其他人，还应该帮助你自己 ...特别是如果你在五年内没有触及它。我写了一些十岁的Perl，我仍然不知道它的作用。

非常脏，我在PHP＆amp; Python，使用反射来检索用户界面中的注释块和标签元素。这是一个用例，尽管很讨厌。

如果使用错误跟踪器，我还会将错误ID放在我的更改附近，以便我有一个返回跟踪器的引用。这是对更改的简要描述（内联更改日志）的补充。

当我做一些我的同事很少看到的东西时......或者当微妙的重要性时，我也违反了“唯一的评论为什么不是什么”的规则。例如：


for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse

Answer 4

我在以下情况下使用评论：

高级API文档注释，即此类或函数是什么？
评论“为什么”。
对更长的代码块执行的简短的高级摘要。这里的关键词是摘要。如果有人想要更多细节，那么代码应该足够清晰，以便他们可以从代码中获取它。这里的要点是让浏览代码的人很容易找出某些逻辑的位置，而不必浏览它的执行细节。理想情况下，这些情况应该被分解为单独的函数，但有时它只是不可行，因为函数将有15个参数和/或不可命名。
如果你真正关注的话，指出通过阅读代码可以看到的微妙之处，但不要因为它们的重要性而引人注目。
当我有充分的理由为什么我需要以hackish方式（性能等）做某事时，不能更清楚地编写代码而不是使用评论。

Answer 5

评论您认为不简单的所有内容，下次您看到您的代码时，您将无法理解。

Answer 6

记录您的代码应该实现认为的内容并不是一个坏主意（特别是如果代码不直观，如果您想将评论保持在最低限度，以便有人在以后阅读它，在调试/修正错误时更容易。虽然在阅读其他人的代码时遇到的最令人沮丧的事情之一是代码已更新的情况，但不是评论....

Answer 7

我总是讨厌用星号填充屏幕一半的评论只是为了告诉你函数返回一个字符串，我从来没有读过那些评论。

一些注释，通常不是格式极端，实际上存在帮助像JavaDoc和Doxygen这样的工具为您的代码生成文档。我认为这是一种很好的评论形式，因为它具有人类和机器可读的文档格式（因此机器可以将其转换为其他更有用的格式，如HTML），使文档接近代码它记录（因此，如果代码更改，文档更有可能更新以反映这些更改），并且通常会向新的大型代码库中的某个人提供一个好的（并且立即）解释，说明为什么存在特定的函数。 / p>

否则，我同意其他所有陈述的内容。评论为什么，只有当它不明显时才发表评论。除了Doxygen评论之外，我的代码通常只有很少的评论。

Answer 8

另一种通常无用的评论是：

// Commented out by Lumpy Cheetosian on 1/17/2009

......呃，好的，源控制系统会告诉我的。它不会告诉我的是为什么Lumpy评论了这段看似必要的代码。由于Lumpy位于Elbonia，我将无法在星期一之前发现他们都从Snerkrumph节日节日回来。

考虑您的受众群体，并降低噪音水平。如果你的评论包含太多不相关的废话，开发人员会在实践中忽略它们。

BTW： Javadoc （或 Doxygen ，或等同物）是一件好事（tm），恕我直言。

Answer 9

我还使用注释来记录特定要求的来源。这样，开发人员以后可以查看导致代码与之相似的需求，如果新需求与其他需求冲突，则在破坏现有流程之前解决该问题。在我工作的地方，要求往往来自不同的人群，他们可能不了解系统必须满足的其他要求。我们还经常被问到为什么我们以某种方式为某个特定客户做某件事，并且有助于能够研究知道我们的跟踪系统中的哪些请求导致代码成为现实。这也可以在源控制系统中保存代码时完成，但我认为这些注释也是注释。

Answer 10

让我想起

Real programmers don't write documentation

Answer 11

我刚才写了这篇评论，从那以后节省了我几个小时：

// NOTE: the close-bracket above is NOT the class Items.
// There are multiple classes in this file.
// I've already wasted lots of time wondering,
// "why does this new method I added at the end of the class not exist?".

好的评论用例

11 个答案: