每个开发者都至少在代码中写过一行注释，一些人为了解释代码写了很多注释。本文收集了一些编写代码注释的实践。
Seattle Area Alt.Net项目组针对写注释的事情进行了讨论。Kelly Leahy倾向于编写自说明性质的代码以及少量的注释。他认为“注释只是说明了系统中不正确的地方”并且他注意到“修改代码的时候经常会忘记了同时修改注释”
[编写注释]编写注释很大程度是依赖于个人习惯。我倾向于写一些简单明了的注释，而不是那种经常会被忘记同步更新的注释。我见过太多这种的情况:代码都已经不存在了，但是注释还在。代码没有紧挨着注释，可能是某个人在代码和注释之前写了新的代码。或者注释本身就是不正确的，因为代码已经被修改了，但是注释没有。
我发现注释太多还不如没有注释，我讨厌大段大段的注释。
Leahy排斥注释，所以他的10000行代码中可能只有1行注释。
如果你的设计当中存在约束条件（比如性能）的时候，注释有时也会非常有用的，而且这种情况也是难以避免的，因为你需要针对约束做一些说明。这种的情况下我也无法避免，所以我们很可能每10000行代码才会有1行注释。（除非是xmldoc注释，对于我个人而言的话，只要公开的API才有写注释的必要，否则那只会是没用的噪音）
Justin Rudd介绍说他的现在项目需要些很多的注释，因为项目中的那些API太混乱了：
我现在正在写一个Visual Studio的源代码管理组件。那些API是在是太混乱了，以至于我不得不在代码中增加注释，这样我会记得这个地方为什么要传递Guid.Empty，而另一个看来类似的地方却要传递一个特殊的GUID。否则，你就会搞砸了。
在现在的解决方案中，我为正在开发的4个事件接口添加了注释，希望下一个开发者不要删除7个函数中的那6个。
我会注释为什么某一个函数需要返回HRESULT，而不是返回S_OK。返回S_OK的时候，Visual Studio Crash了。（在关联的地方，这类的事情会被注释）
我还注释那些文档中说你可以传递null的地方，事实上却不可以。
在这个项目中，代码和注释的比例可能有2：1。
Chris Tavares用注释来标记解决Bug：
事实上，这类注释“//这么做是为了解决什么bug”不是坏味道，而是必须的。
但是Brandon Molina认为修改Bug的注释最好可以记录在版本控制系统中，而不是在代码内：
这样修改10个Bug之后会怎样呢？你可能有一大段没用的注释，这会让你的代码看来更加混乱。还是使用版本控制系统吧。这样在你对比代码是，结合上下文的意思，注释会变得非常有用。
Brad Wilson提出了一个添加注释的原则：
“为什么”型注释 == 好注释
“怎样实现”型注释 == 不好的注释
在code comments上，Timothy Hilden坚持需要一些好的注释：
不写注释是很容易的。说实话吧，我们这些开发人员又不是为了获取普利策奖，这不是表现个人能力，这只是关乎是否懒的问题。
说实话，当代码需要注释而没有注释的时候，那会更糟糕。首先，这是对同事的一种不尊重。每个人都知道，当原作者在度假，或者离职，或者是其他原因导致原作者无法提供帮助的时候，需要去看那些含糊不清的，无法自说明的类和方法，会有多么地沮丧。程序员就像文章的作者，而后面的程序员就像是读者。就像作者一样，我们应该学会尊重我们的读者。
其次，不写注释的程序员对于自己过于自信。毫无疑问，我们在写代码的时候总是很有思路。但是在编程时，我们总是要同时考虑好几件事情。当你下次回过头再来看这些代码的时候，你很难回想起当时编写代码的思路。这种情况下，就应该在某个地方添加注释了。
Hilden不支持不正式文档——Scott Swigart 和 Jeff Atwood 几年前提到的一个例子——就是过度使用注释的情况
他建议将所有的这些代码合并到一行，而不是注释每一步代码：
您编写注释的习惯是什么？这些习惯是公司强制要求的，还是你自己选择的？你是否支持那种尽可能少的注释政策，相信下一个开发者会理解你的代码，还是认为你应该花一些时间来注释那些不太清晰的代码。
【原文链接：http://www.infoq.com/news/2010/03/To-Comment-or-Not-to-Comment】
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
