本文发表在作者josé m. aguilar的博客variable not found，后来由timm martin翻译成英文发表在devtopics上。
以下是如何注释代码的13tips，它们会在日后帮助你更容易理解和维护代码。
1. comment each level（每个级别的注释有统一的风格）
注释每一个代码块，并且在各个级别的代码块上，要使用统一的注释方法。例如：
对于类，应包含简单的描述、作者以及最近的更改日期
对于方法，应包含目的的描述、功能、参数以及返回值
使用统一的注释规则对于一个团队是非常重要的。当然，更加推荐使用注释的约定和工具（例如，c#的xml或java的javadoc），它们会是注释变得更加容易。
2. use paragraph comments（对段落注释）
将代码块分成若干完成独立功能的段落，并在每个段落前添加注释，向读者说明即将发生什么。
// 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. align comments in consecutive lines（对齐注释行）
对于拥有后缀式注释的多行代码，排版注释代码，使各行注释对齐到同一列。
const max_items = 10; // maximum number of packets
const mask = 0x1f; // mask bit tcp
一些开发人员使用tab来对齐注释，有些则使用空格。但是由于tab在不同的编辑器或者ide上会有所不同，最好还是使用空格。
4. don't insult the reader's intelligence（不要侮辱读者的智商）
不要写没用的注释，例如：
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
写这种无用的注释不但浪费你的时间，而且读者在读这种很容易理解的代码时，很容易被你的注释转移注意力，浪费了时间。
5. be polite（要有礼貌）
不要写不礼貌的注释代码，例如注意，愚蠢的使用者输入了一个负数，或者修正由于最初的开发者的可怜且愚蠢的编码所造成的副作用。这样的注释冒犯了作者，而且你并不知道谁会在将来读到这段注释--你老板、客户或者是你在注释中冒犯的那个可怜且愚蠢的开发人员。
6. get to the point（简明扼要）
不要在注释中写的过多，不要写玩笑、诗和冗长的话。总之，注释需要简单直接。
7. use a consistent style（风格一致）
一些人认为注释应该能让非程序员也能看懂，但是也有些人认为注释仅仅是指导程序员的。不管怎么说，像《successful strategies for commenting code》中所说，真正重要的是注释始终面向同一个读者，在这点上，应该保持一致。个人认为，我很怀疑会有非程序人员阅读代码，所以应该把阅读注释的对象定位为开发人员。
int estimate(int x, int y)
{
// todo: implement the calculations
return 0;
}
9. comment code while writing it（写代码的同时，完成注释）
写代码的同时添加注释，因为此时你的思路最为清晰。如果你把注释的任务留到最后，那么你相当于经历了两次编码。我没有时间注释我太忙了项目耽误了这些往往是不写注释的理由。所以，程序员们认为，最理想的解决方法是‘写代码前先写注释'。例如：
public void processorder()
{
// make sure the products are available
// check that the customer is valid
// send the order to the store
// generate bill
}
10. write comments as if they were for you (in fact, they are)把代码的读者想象成你自己（实际情况往往如此）
注释代码时，不仅仅要为将来可能维护你代码的人考虑，而且要考虑到读注释的可能是你。伟大的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. update comments when you update the code（更新代码时，记得更新注释）
如果不能随着代码的更新而更新注释，那么即使再准确的注释也毫无意义。代码和注释必须同步，否则这些注释对于维护你代码的程序人员来说简直是折磨。在使用refactoring工具自动更新代码时，应尤其注意，它们会自动更新代码而不会改变注释，这些注释自然就过期了。
12. the golden rule of comments: readable code（可读性良好的代码是最好的注释）
对于许多程序员来说，基本的原则之一就是：让代码自己说话。有人可能会怀疑这是那些不爱写注释的程序员的借口，然而这确实是一个不争的事实。自我解释良好的代码对于编码来说大有益处，不但代码容易理解甚至使注释变得没有必要。举例来说，在我的文章《fluid interfaces》中展示了什么是清晰的自我解释型代码：
calculator calc = new calculator();
calc.set(0);
calc.add(10);
calc.multiply(2);
calc.subtract(4);
console.writeline( result: {0}, calc.get() );
在本例中，注释是没必要的，并且会违背tip#4 。为了使代码更加可读，应该考虑使用适当的名字（像在经典的《ottinger's rules》描述的），确保正确的缩进和代码风格栏线（代码风格栏线是类似于#region #endregion这类的东西吧？）。如果这一点做的不好，直接后果是，你的注释看起来就像是在为晦涩难懂的代码而道歉。
13. share these tips with your colleagues（与你的同事share这些tips）
尽管tip#10中曾说过良好的注释会是自己从中收益，但是这些tips会使所有开发人员收益，尤其是在团队合作的环境中。因此大方的与同事分享这些注释的技巧，让我们都能写出易懂而且好维护的代码。