养成好习惯 关于代码注释的7个技巧

1、对不同级别的代码进行注释

对于不同级别的代码块，要使用统一的方法来进行注释。例如：

对于每一个类，需要包含一段简明扼要的描述，作者和上一次修改的时间

对于每一个方法，需要包含这个方法的用途，功能，参数以及返回结果

当你在一个团队里面的时候，采用一套注释的标准是非常重要的。当然，使用一种大家都认可的注释约定和工具(例如C#的XML注释和Java的Javadoc)在一定程度上能推动这项任务。

2、使用段落注释

首先把代码块分解成多个“段落”，每一个段落都执行单一的任务;然后在每一个“段落”开始之前添加注释，告诉阅读代码的人接下来的这段代码是干什么用的

3、对齐注释行

对于那些在行末写有注释的代码，应该对齐注释行来使得方便阅读

有些开发人员使用tab来对齐注释，而另外一些人会用空格来对齐。由于tab在不同的编辑器和集成开发环境中会有所不同，所以最佳的方法是使用空格来对齐注释行。

4、不要侮辱阅读者的智慧

要避免没用的注释，这不单把时间浪费在写没用的注释上面，同时也在分散读者的注意力。

5、要有礼貌

应当避免没有礼貌的注释，例如“要注意一些愚蠢的用户会输入一个负数”，或者“修正由菜鸟工程师写的愚蠢得可怜的代码而导致的副作用”。这样的注释对于代码的写注释的人来说并没有任何好处，同时你永远都不会知道将来这些注释会被谁来阅读，你的老板，一个客户或者是刚才被你数落的愚蠢得可怜的工程师。

6、直截了当

不要在注释里面写过多的废话。避免在注释里面卖弄ASCII艺术，写笑话，作诗和过于冗长。简而言之就是保持注释的简单和直接。

7、使用统一的风格

有些人觉得注释应该让非程序员也能看懂。另外一些人觉得注释需要面对的读者只是程序员。无论如何，正如Successful Strategies for Commenting Code中所说的，海淘科技建站公司最重要的是注释的风格需要统一，并且总是面向相同的读者。就自己而论，我怀疑非程序员是否会去读代码，所以我觉得注释应该面向程序员来写。

8、使用特有的标签

在一个团队工作中工作时，为了便于与其它程序员沟通，应该采用一致的标签集进行注释。例如，在很多团队中用TODO标签表示该代码段还需要额外的工作。

9、区域注释 在实际工作中，有时会出现分不清注释应该在标签之上还是标签之下，为了避免这种情况，注释信息统一写在区域标签开始之前和结束之后，并以“S”或“E”开始，表示区域注释的开始或结束。 

10、单行注释 注释信息应写在需注释的内容区域里 

11、注释层级 在模块制作中，可能会出现区域中还有区域的情况，为了更好的区分区域之间的层级，引入了注释层级的概念。 区域注释前面的等号表示了当前注释的层级 

12、在内部使用特殊的标签

当你在一个团队里工作的时候，采用一组一致的标签能帮助不同的程序员沟通。例如，很多团队会采用“TODO”标签来表示一段尚未完成的代码

标签注释并不会解释代码，它们寻求注意或者是传递信息。但是如果适当地使用这种技术，要记住跟进这段代码并且完成该标签传递的任务。

13、更新代码的时候要更新注释

如果注释没有随着代码的修改而更新，那么这些注释将是毫无意义的。代码和注释需要同步，否则注释只会让维护代码的开发者更加痛苦。需要特别注意的是，一些重构的工具会自动更新代码，但是却没有自动更新注释，那么注释就自然而然地过期作废了。

14、良好可读性代码是注释的金科玉律

对于很多开发者来说，一个基本的原则就是：让代码自己描述自己。虽然有人怀疑这是由不喜欢写注释的程序员所倡导的一场运动，但是无需解释的代码有很大的好处，这些代码更加容易理解甚至让注释变得没有必要。例如，在我的文章Fluid Interfaces中就给大家展示了什么是清晰的无需解释的代码。

在这个例子里面，注释就像是违反了第4条技巧那样，变得毫无必要。要写出可读性好的代码，你需要使用适当的命名方式(在经典的Ottinger’s Rules中有阐述)，保证恰当的缩进，并且采用编码风格指导。如果代码不遵守这条技巧，那么注释看起来就好像是为自己不好的代码的写道歉信一样。

15、跟你的同事分享这些技巧

虽然从第10条技巧中我们已经知道了自己就是好注释的得益者，但是这些技巧对于所有的开发者来说都是很有帮助的，尤其是整个团队都有相同共识的情况下。因此，大方地跟你的同事去分享这些技巧，让我们写出更加容易理解和维护的代码。