注释代码技巧之三

对齐注释行

对于拥有后缀式注释的多行代码，排版注释代码，使各行注释对齐到同一列。

const MAX_ITEMS = 10; // maximum number of packets

const MASK = 0x1F; // mask bit TCP

一些开发人员使用tab来对齐注释，有些则使用空格。但是由于tab在不同的编辑器或者IDE上会有所不同，最好还是使用空格。

不要无意义的注释

不要写没用的注释，例如：

if (a == 5) // if a equals 5

counter = 0; // set the counter to zero

写这种无用的注释不但浪费你的时间，而且读者在读这种很容易理解的代码时，很容易被你的注释转移注意力，浪费了时间。

要有礼貌、简明

不要写不礼貌的注释代码，例如"注意，愚蠢的使用者输入了一个负数"，或者"修正由于最初的开发者的可怜且愚蠢的编码所造成的

副作用"。这样的注释冒犯了作者，而且你并不知道谁会在将来读到这段注释--你老板、客户或者是你在注释中冒犯的那个可怜且愚

蠢的开发人员。

不要在注释中写的过多，不要写玩笑、诗和冗长的话以及与所注释代码无关的话。总之，注释需要简单直接。

风格一致

注释始终面向同一个读者，在这点上，应该保持一致。个人认为，我很

怀疑会有非程序人员阅读代码，所以应该把阅读注释的对象定位为开发人员。

 写代码的同时，完成注释

写代码的同时添加注释，因为此时你的思路最为清晰。如果你把注释的任务留到最后，那么你相当于经历了两次编码。"我没有时间

注释""我太忙了""项目耽误了"这些往往是不写注释的理由。所以，程序员们认为，最理想的解决方法是‘写代码前先写注释'。例

如：

public void ProcessOrder()

{

// Make sure the products are available

// Check that the customer is valid

// Send the order to the store

// Generate bill

}

Write comments as if they were for you (in fact, they are)把代码的读者想象成你自己（实际情况往往如此）

注释代码时，不仅仅要为将来可能维护你代码的人考虑，而且要考虑到读注释的可能是你。

结果，我们自己往往是我们良好注释的受益者，或者是烂注释的受害人。

更新代码时，记得更新注释

如果不能随着代码的更新而更新注释，那么即使再准确的注释也毫无意义。代码和注释必须同步，否则这些注释对于维护你代码的

程序人员来说简直是折磨。

可读性良好的代码是最好的注释

对于许多程序员来说，基本的原则之一就是：让代码自己说话。有人可能会怀疑这是那些不爱写注释的程序员的借口，然而这确实

是一个不争的事实。自我解释良好的代码对于编码来说大有益处，不但代码容易理解甚至使注释变得没有必要。举例来说，在我的

文章《Fluid Interfaces》中展示了什么是清晰的自我解释型代码：

Calculator calc = new Calculator();

calc.Set(0);

calc.Add(10);

calc.Multiply(2);

calc.Subtract(4);

Console.WriteLine( "Result: {0}", calc.Get() );