logo标签列表

评论的好用例子

formattingcommentsuse-case
11

我一直很讨厌那些用星号填满半个屏幕只为告诉你这个函数返回一个字符串的注释，我从来不看那些注释。

然而，我会阅读描述为什么要这样做以及如何实现的注释（通常是代码中的单行注释）；这些对于理解别人的代码非常方便。

但是当写注释时，我不会写那种注释，相反，我只在编程竞赛中编写算法时使用注释，我会考虑算法将如何执行它的操作，然后在注释中写下每个步骤，然后编写与该注释相应的代码。

例如：

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

除此之外，我无法想象为什么有人会浪费宝贵的时间写评论，而不是编写代码。

我是对还是错？我有什么遗漏的吗？我不知道其他好的评论用途吗？

7
重复几次，用不同的方式重新表述：http://stackoverflow.com/questions/tagged?tagnames=comments&sort=votes - Roger Pate
11个回答
17

评论应该表达为什么你要做某件事，而不是你正在做什么。

3
任何人都可以阅读代码，了解你在做什么。但是为什么这样做可能完全成谜，除非有一些解释。 - S.Lott
18
这个陈词滥调总是被反复使用。尝试阅读一大段没有注释的C语言或汇编代码，看看你是否能理解它在做什么。注释需要涵盖为什么和什么两个方面。 - anon
2
此外，其他人很难知道你的函数某些行为是否是有意为之。没有注释，其他人可能会“修复”本来就没有问题的代码，或者他们可能认为修复看起来错了的东西太冒险了，而实际上确实需要修复。 - Scott Smith
2
应该在“为什么”后面加上“如果不明显”。我见过太多“递增i以便我可以计数”的注释。 - pestilence669
1
“Why”也可以扩展为解释“为什么选择这种方法而不是其他可能适合的方法”。 - Peter M
显示剩余10条评论
6

这是一个古老的格言，但一个好的衡量标准是：

解释“为什么”你要做某事，而不是“如何”去做。

仅从代码上看，对于即使是初学者程序员来说，“循环遍历n到j-1之间的所有名称”应该是立即清晰的。提供为什么要这样做的原因可以帮助提高可读性。

1
@TIm 哈哈，不，你应该注释代码。这是常识，常识，常识。 - JeremyDWill
5
如果你使用像Doxygen这样的东西，你可以完全记录你的返回类型、参数等，并生成一个漂亮的“源代码手册”。我经常为客户做这个，这样继承我的代码的团队就不会完全迷失（或被迫审查每个头文件）。
文档块通常被过度使用，特别是在强类型语言中。对于像Python或PHP这样的语言来说，详细说明更有意义，而对于C++或Java来说则不是那么重要。尽管如此，对于方法和成员不太自解释的情况（例如没有命名为update的情况），仍然很好用。
通过注释我想要告诉自己的内容，我已经节省了很多思考时间。注释应该不仅帮助他人，而且还应该帮助你自己...特别是如果你五年没碰它了。我有一些十年前写的Perl代码，我现在仍然不知道它是干什么的。
在PHP和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
我喜欢其中关于如果你第一次或很久以前第一次看它时想要了解什么的部分。根据我的经验，这也更倾向于“为什么”而不是“什么”。 - GalacticCowboy
4

我在以下情况下使用注释：

  1. 高级API文档注释，即这个类或函数是用来做什么的？
  2. 解释“为什么”。
  3. 一个长代码块的简短、高层次的总结。关键词是总结。如果有人想要更多细节，代码应该足够清晰，他们可以从代码中得到它。这里的重点是使浏览代码的人能够轻松地找出某个逻辑块的位置，而不必深入了解它是如何执行的。理想情况下，这些情况应该被拆分成单独的函数，但有时候这是不可行的，因为函数可能有15个参数和/或不能命名。
  4. 指出细微之处，如果你真的很注意阅读代码，但它们不像它们应该给予其重要性那样显眼。
  5. 当我有一个充分的理由为什么我需要用hackish的方式去做某件事（性能等）并且不能更清晰地编写代码而不是使用注释。
2

注释掉一切你认为不够直截了当的部分，这样下次你看代码时就能够理解了。

这实际上是我在自己的代码中进行注释的方式之一。由于某些怪癖，我有时不得不做一些花哨的技巧，而其他人可能无法自动捕捉到这些技巧-因此，我会在注释中写下它们。 - Phil
1

记录下你认为代码应该实现的内容并不是个坏主意（尤其是当代码不直观且你想尽量减少注释时），这样在以后调试/修复 bug 时，阅读代码的人会更加轻松。虽然在阅读别人的代码时最令人沮丧的事情之一是遇到代码已经更新但注释没有更新的情况...

如果代码不直观，我会在重要和混乱的部分注释是什么以及如何实现，这样维护人员就可以理解正在发生的事情。我还会注释为什么，以便他们知道可以期望什么，但这是一种需要记录“如何”的情况。 - Chris Lutz
0

另一种通常没有用的注释类型是：

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

...嗯，好的，源代码控制系统应该会告诉我这个。但它不会告诉我为什么Lumpy注释掉了这个看似必要的代码片段。由于Lumpy位于Elbonia，我将无法在他们从Snerkrumph节日回来之前找到答案。

考虑你的受众，并降低噪音水平。如果你的评论包含太多无关紧要的东西，开发人员实际上会忽略它们。

顺便说一下：Javadoc（或 Doxygen，或等效物）是一个好东西（在我看来）。

我必须说，我喜欢你所想出的名字。 - Leo Jweda
0

我之前写了这个评论，它已经为我节省了很多时间：

// 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?".
0
我一直讨厌那些用星号填满半个屏幕的注释，只是为了告诉你这个函数返回一个字符串，我从来不读那些注释。
有些类似的注释，通常没有那么极端的格式，实际上是为了帮助像JavaDoc和Doxygen这样的工具生成代码文档。我认为这是一种很好的注释形式，因为它既有人类可读的文档格式（这样机器可以将其转换为其他更有用的格式，如HTML），又将文档放在与之相关的代码附近（这样如果代码发生变化，文档更有可能被更新以反映这些变化），并且通常对于一个新接触大型代码库的人来说，能够立即解释为什么存在某个特定的函数。
除此之外，我同意之前提到的所有观点。只有在不明显的情况下才进行注释，并且除了Doxygen注释之外，我的代码通常很少有注释。
这就是我所说的那种注释，看一下这里第98行的注释和函数：http://code.google.com/p/google-web-toolkit/source/browse/trunk/user/src/com/google/gwt/user/client/ui/TextBox.java?spec=svn7480&r=7480这是来自Google编写的GWT中TextBox的源代码。 - Leo Jweda
@Laith - 我讨厌使用嵌入XML或HTML进行格式化的任何注释文档格式，但通常Doxygen还不错。那个特定的代码片段具有很高的注释-代码比率，但它还展示了被人所憎恶的 i ++; // 将i后置加1 的注释风格，所以忽略它。另外，我主要使用C语言，因此对于我的平均用例来说，大多数代码都会略微冗长。 - Chris Lutz
0
我也使用注释来记录特定需求的来源。这样，开发人员以后可以查看导致代码变成现在这样的需求，并且如果新需求与其他需求冲突，则可以在破坏现有流程之前解决冲突。在我的工作中，需求通常来自不同的人群，他们可能不知道系统必须满足的其他需求。我们经常被问及为什么要以某种特定的方式为特定客户执行某个操作，因此能够进行研究以了解跟踪系统中的请求是如何导致代码变成现在这样的状态非常有帮助。这也可以在将代码保存到源控制系统时完成，但我认为这些注释也是注释。
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接