代码编程规范—— 注释规范

良好的注释规范可以为团队合作开发推波助澜，无论在项目开发，还是产品维护上都起到了至关重要的作用。应该说注释规范是一种约定，也是程序员之间良好沟通的桥梁。

   我们从现在就应该养成良好的编程规范，严格要求自己，米老师常说“要想成为高端人才，就对自己的要求高一点”。加油！

注释规范：

             

a)  注释中，应标明对象的完整的名称及其用途，但应避免对代码过于详细的描述。

b)  每行注释的最大长度为100个字符。

c)  将注释与注释分隔符用一个空格分开。

d)  不允许给注释加外框。

e)  编码的同时书写注释。

f)  重要变量必须有注释。

g)   变量注释和变量在同一行，所有注释必须对齐，与变量分开至少两个“Tab”键。

如：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">int  iLevel, iCount;     // iLevel ....tree level  
2.   
3.                                        // iCount ....count of tree items   
4.   
5.      string strSql;            //SQL  
6.   
7. </span>  

h)  典型算法必须有注释。

i)  在循环和逻辑分支地方的上行必须就近书写注释。

j)   程序段或语句的注释在程序段或语句的上一行.

k)  在代码交付之前，必须删掉临时的或无关的注释。

l)   为便于阅读代码，每行代码的长度应少于100个字符。

 

对于自己创建的代码文件（如函数、脚本），在文件开头，一般编写如下注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">/******************************************************      
2.   
3. FileName:  
4.   
5. Copyright  (c)  2010-xxxx  
6.   
7. Writer: 某某某  
8.   
9. Create Date:  
10.   
11. Rewriter:  
12.   
13. Rewrite Date:  
14.   
15. Impact:  
16.   
17. Main Content（Function Name、parameters、returns）  
18.   
19.                   ******************************************************/  
20.   
21. </span>  

 

 

模块开始必须以以下形式书写模块注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">///<summary>  
2.   
3. ///Module ID：<模块编号，可以引用系统设计中的模块编号>  
4.   
5. ///Depiction：<对此类的描述，可以引用系统设计中的描述>  
6.   
7. ///Author：作者中文名  
8.   
9. ///Create Date：<模块创建日期，格式：YYYY-MM-DD>  
10.   
11. ///</summary>  
12.   
13. </span>  

 

 

如果模块只进行部分少量代码的修改时，则每次修改须添加以下注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">///Rewriter：Rewrite Date：<修改日期，格式：YYYY-MM-DD>  Start1：           
2.   
3. /* 原代码内容*/  
4.   
5. ///End1：                                  
6.   
7. 将原代码内容注释掉，然后添加新代码使用以下注释：  
8.   
9. ///Added by： Add date：<添加日期，格式：YYYY-MM-DD>   Start2：          
10.   
11. 新代码内容  
12.   
13. ///End2：                       
14. </span>  

           

 

 

如果模块输入输出参数或功能结构有较大修改，则每次修改必须添加以下注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">///<summary>  
2.   
3. ///Log ID：<Log编号,从1开始一次增加>  
4.   
5. ///depiction：<对此修改的描述>  
6.   
7. ///Writer：修改者中文名  
8.   
9. ///Rewrite Date：<模块修改日期，格式：YYYY-MM-DD>  
10.   
11. ///</summary>  
12.   
13. </span>  

   

 

 

在类的属性必须以以下格式编写属性注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">///<summary>  
2.   
3. /// <Properties depiction>  
4.   
5. /// </summary>  
6.   
7. </span>  

在类的方法声明前必须以以下格式编写注释

     

[sql] view plaincopyprint?

1. <span style="font-size:18px;">   ///<summary>  
2.   
3.         ///depiction：<对该方法的说明>  
4.   
5.         ///</summary>  
6.   
7.         ///<param name="<参数名称>"><参数说明></param>  
8.   
9.              ///<returns>  
10.   
11.              ///<对方法返回值的说明，该说明必须明确说明返回的值代表什么含义>  
12.   
13.       ///</returns>  
14.   
15.         ///Writer：作者中文名  
16.   
17.         ///Create Date：<方法创建日期，格式：YYYY-MM-DD>  
18.   
19. </span>  

       

 

代码间注释分为单行注释和多行注释：

    单行注释：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">//<单行注释>  
2.   
3.      多行注释：  
4.   
5.      /*多行注释1  
6.   
7.      多行注释2  
8.   
9.      多行注释3*/  
10.   
11. </span>  

代码中遇到语句块时必须添加注释（if,for,foreach,……）,添加的注释必须能够说明此语句块的作用和实现手段（所用算法等等）。

 

1. Comment each level（每个级别的注释有统一的风格）

注释每一个代码块，并且在各个级别的代码块上，要使用统一的注释方法。例如：

对于类，应包含简单的描述、作者以及最近的更改日期
对于方法，应包含目的的描述、功能、参数以及返回值

使用统一的注释规则对于一个团队是非常重要的。当然，更加推荐使用注释的约定和工具（例如，C#的XML或Java的Javadoc），它们会是注释变得更加容易。

2. Use paragraph comments（对段落注释）

将代码块分成若干完成独立功能的"段落"，并在每个"段落"前添加注释，向读者说明"即将发生什么"。

[sql] view plaincopyprint?

1. <span style="font-size:18px;">// Check that all data records  
2.   
3. // are correct   
4.   
5. foreach (Record record in records)   
6.   
7. {  
8.   
9. if (rec.checkStatus()==Status.OK)  
10.   
11. {   
12.   
13. . . .   
14.   
15. }   
16.   
17. }   
18.   
19. // Now we begin to perform   
20.   
21. // transactions   
22.   
23. Context ctx = new ApplicationContext();   
24.   
25. ctx.BeginTransaction();  
26.   
27. . . .  
28.   
29. </span>  

3. Align comments in consecutive lines（对齐注释行）

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

[sql] view plaincopyprint?

1. <span style="font-size:18px;">const MAX_ITEMS = 10; // maximum number of packets   
2.   
3. const MASK = 0x1F; // mask bit TCP   
4.   
5. </span>  

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

4. Don't insult the reader's intelligence（不要侮辱读者的智商）

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

[sql] view plaincopyprint?

1. <span style="font-size:18px;">if (a == 5) // if a equals 5   
2.   
3. counter = 0; // set the counter to zero  
4.   
5. </span>  

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

5. Be polite（要有礼貌）

不要写不礼貌的注释代码，例如"注意，愚蠢的使用者输入了一个负数"，或者"修正由于最初的开发者的可怜且愚蠢的编码所造成的副作用"。这样的注释冒犯了作者，而且你并不知道谁会在将来读到这段注释--你老板、客户或者是你在注释中冒犯的那个可怜且愚蠢的开发人员。

6. Get to the point（简明扼要）

不要在注释中写的过多，不要写玩笑、诗和冗长的话。总之，注释需要简单直接。

7. Use a consistent style（风格一致）

一些人认为注释应该能让非程序员也能看懂，但是也有些人认为注释仅仅是指导程序员的。不管怎么说，像《Successful Strategies for Commenting Code》中所说，真正重要的是注释始终面向同一个读者，在这点上，应该保持一致。个人认为，我很怀疑会有非程序人员阅读代码，所以应该把阅读注释的对象定位为开发人员。

8. Use special tags for internal use（在内部使用特殊的标签）

团队中处理代码时，在程序员之间应采用一系列统一的‘标签注释'进行交流。例如，很多团队使用"TODO"来表示一段需要额外工作的代码。

[sql] view plaincopyprint?

1. <span style="font-size:18px;">int Estimate(int x, int y)   
2.   
3. {  
4.   
5. // TODO: implement the calculations   
6.   
7. return 0;  
8.   
9. }  
10.   
11. </span>  

‘标签注释'并不解释代码，而是引起主意或者传递信息。但是，使用这种方法时，务必要完成‘标签注释'传递的信息。

9. Comment code while writing it（写代码的同时，完成注释）

写代码的同时添加注释，因为此时你的思路最为清晰。如果你把注释的任务留到最后，那么你相当于经历了两次编码。"我没有时间注释""我太忙了""项目耽误了"这些往往是不写注释的理由。所以，程序员们认为，最理想的解决方法是‘写代码前先写注释'。例如：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">public void ProcessOrder()   
2.   
3. {  
4.   
5. // Make sure the products are available  
6.   
7. // Check that the customer is valid   
8.   
9. // Send the order to the store   
10.   
11. // Generate bill   
12.   
13. }  
14.   
15. </span>  

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》中展示了什么是清晰的自我解释型代码：

[sql] view plaincopyprint?

1. <span style="font-size:18px;">Calculator calc = new Calculator();  
2.   
3. calc.Set(0);  
4.   
5. calc.Add(10);  
6.   
7. calc.Multiply(2);  
8.   
9. calc.Subtract(4);  
10.   
11. Console.WriteLine( "Result: {0}", calc.Get() );  
12.   
13. </span>  

在本例中，注释是没必要的，并且会违背tip#4 。为了使代码更加可读，应该考虑使用适当的名字（像在经典的《Ottinger's Rules》描述的），确保正确的缩进和代码风格栏线（代码风格栏线是类似于#region #endregion这类的东西吧？）。如果这一点做的不好，直接后果是，你的注释看起来就像是在为晦涩难懂的代码而道歉。

13. Share these tips with your colleagues（与你的同事share这些tips）

尽管tip#10中曾说过良好的注释会是自己从中收益，但是这些tips会使所有开发人员收益，尤其是在团队合作的环境中。因此大方的与同事分享这些注释的技巧，让我们都能写出易懂而且好维护的代码。