Tips to Comment Your Code
Tips to Comment Your Code
（原文地址：http://www.devtopics.com/13-tips-to-comment-your-code/）
这篇文章是西班牙的jose M.Aguilar在他优秀的blog variable not found里发表的，得到他的允许后，Timm martin翻译修改后重新在这里发布。
下面13条技巧是关于如何如何注释你的代码，使得它即使随着时间的流逝仍易于理解和维护。
1.注释每一级
注释每一个代码块，对于每一级别的代码使用统一的注释方法.比如：
*针对每个类，注释包含一个简单的描述，作者和最近修改日期。
*针对每个方法，包括一个它目的的描述，功能，参数和结果.
当在一个团队里采用一个注释标准是重要的。当然，为了有利于注释任务使用注释约定和工具（例如在C#里用XML，JAVA里使用JAVADOC）是可接受的。
2.使用段落注释。
将代码块多个代码段，每个代码段完成一个简单的任务，然后在每个代码块开始处添加备注告知读者它将要做什么。
// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
3.将注释摆列成连续的一行
对于多行的代码使用跟在行后的注释，将会更容易阅读。
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
一些开发者使用tab键来排列注释，但是其他人使用空格。tab会有不方便的地方，在编辑器和IED的切换中tab的效果可能会改变,最好的方式还是使用Space.(这点我不赞成，还是用TAB好，有IDE的情况下，没人会用编辑器吧^_^ 不过如果有耐心使用SPACE使得效果像TAB一样那最好)
4.不要侮辱读者的智商
避免显而易见的注释，像下面这样：
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
这浪费你的时间写不需要的注释，并且使用可以轻易从代码推断出来的细节来使读者困惑。
5.文雅的注释
避免粗鲁的注释，像这样，“注意愚蠢的用户已经输入一个负数” 或者 “这里修补了最初可怜不称职的开发者实现的产品的侧面效果”。对他们的作者这样的注释不会好的反应，并且你也不会知道将来谁可能读到这些注释，也许是你的老板，客户，或者刚刚被你侮辱的那位可怜的不称职的开发者。（谁会这么无聊^_^）
6．在注释列写多余你需要传达的意思文字。避免ASCII字符，玩笑，诗和太紧凑（hyperverbosity） .简短，保持注释的简单和直接。
7. 使用一致的风格
一些人相信注释应该写到可以让非程序员明白的程度。另外一些人认为注释仅仅指导开发人员。在任何事件中，如文章Successful Strategies for Commenting Code里说明的，问题的实质是注释的组成和面对的是不是总是同样的读者。就我而言，我不怀疑会有很多非开发者会读到代码，因为注释还应该面向另外的开发者。
8. 针对内部用户使用专门的标记
当作为一个团队进行编码工作时，应该采用一套标记在程序员中间交流。例如，许多团队使用一个”TODO:”标记来指出需要附加工作的代码部分：
int Estimate(int x, int y)
{
// TODO: implement the calculations
return 0;
}
标记注释不是解释代码,而是提出需要注意或者表达一个信息。但是如果你使用这个方法，记住要弄清楚实际做的时候需要什么信息。
9.当你写代码的时候同时注释它。
当你写代码的时候同时注释它，这样它在你的记忆力是新的。如果你直到最后才全部去注释，你将花费两倍长的时间。“我没有时间去注释”，“我很忙”或者“项目被延时了”这些都只不过是避免给你代码写文档的借口。有些开发者认为在写代码之前，应该先写注释，作为计划你最终的解决方案的一个方法。比如：
public void ProcessOrder()
{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
10.如同他们是本该做的一样的写注释（事实上，他们的确是）Phil Haack里有一段很棒的词语:
当注释代码时，不仅要考虑将来那些需要维护你的代码的开发人员，还需要为你自己考虑。在
("As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.")
一行代码一被放置到屏幕上你就应该进入到这片代码的维护模式中。
结果就是，我们自己会成为好的（或者坏的）注释的第一个受益者。
11. 当你更新代码时更新注释。
如果注释没有跟随代码改变，There is no point in commenting correctly on code（惭愧，不明白它的意思……）。代码和注释必须同步改变，否则对于将要维护的代码的开发人员注释将变成更加困难。特别注意重构工具，它们会更新你的代码但是注释却没有改变!
12.注释的黄金准则：可读性的代码
对于大多数开发人员的基本准则之一：让你的代码能说明自己。尽管有些人猜想这个准则是由那些不愿意写注释的开发人员造成的,但是自解释的代码对编写更容易理解代码的确大有帮助。比如，在我的文章Fluid Interfaces里清楚的显示了自解释的代码：
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
在这个例子里，并不需要注释，那可能会违反了第4条。为了让代码更有可读性，你可以考虑使用特定的名字（比如经典的文章Ottinger's Rules里的描述）,保证正确的缩排，并且要有代码风格。对于糟糕的代码，失败的遵守这个规则可能导致在apologize看到的注释。
13.跟你的同事分享这些技巧。
第10条技巧说明我们怎样从好的注释里得到好处，这些技巧对于所有开发者都是有益的，特别在团队里一起工作的。因此，为了能编写容易明白和维护代码跟你的同事分享这些注释技巧吧。
14. The code should explain how.
The comments should explain why. （回复在看到的，我觉得还不错。）
