代码注释（Code comments）

   

                                       代 码 注 释（Code comments）

　　

　　在理解三层和机房三层+设计模式时，特别是三层运行时，师傅狠狠的指导了一
番，必须要一行一行运行原则，和怎么运行的，自己要能说出是怎么运行出来。 当初查

了一些网上资料，稂莠不齐，所以自己总结了一些代码注释的原则，还请多多指点：
　　

　　代码的标准是英文，它的母语就是英文，现在不论是中国人、日本人还是俄国人在
开发软件，为了更好的理解和开发软件，都很有必要写一些相应的注释，为了更好的更

改、维护等工作，代码注释不是必须的，但是它可以提高程序的可读性，建议养成写注释的习惯，基本的注释要求在20%~30%左右，有了代码的注释到时候自己也能更快更好的理解。

规范示例：

/头文件的头注释/*************************************************  Copyright (C), ２０１３, DanielStark  File name:         // 文件名  Author:       Version:        Date: 2013.3.02 DanielStark  // 作者、版本及完成日期  Description:                                     <pre name="code" class="csharp">/*************************************************  Function:       // 函数名称  Description:    // 函数功能、性能等的描述  Calls:          // 被本函数调用的函数清单  Called By:      // 调用本函数的函数清单  Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）  Table Updated:  // 被修改的表（此项仅对于牵扯到数据库操作的程序）  Input:          // 输入参数说明，包括每个参数的作                  // 用、取值说明及参数间关系。  Output:         // 对输出参数的说明。  Return:         // 函数返回值的说明  Others:         // 其它说明*************************************************/

// 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1. .... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification:

  　 *************************************************/
　　源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及

其功能、修改日志等。

示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

/************************************************************  Copyright (C), 2013.3.02   DanielStark,   信息技术提高班  FileName: test.cpp  Author:        Version :          Date:  Description:     // 模块描述       Version:         // 版本信息  Function List:   // 主要函数及其功能    1. -------  History:         // 历史修改记录      <author>  <time>   <version >   <desc>      David    96/10/12     1.0     build this moudle 

**********************************************************/

  　函数头部应进行注释，列出：函数的目的/ 功能、输入参数、输出参数、返回值、

调用关系（函数、表）等

示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包

含在内

/*************************************************  Function:       // 函数名称  Description:    // 函数功能、性能等的描述  Calls:          // 被本函数调用的函数清单  Called By:      // 调用本函数的函数清单  Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）  Table Updated:  // 被修改的表（此项仅对于牵扯到数据库操作的程序）  Input:          // 输入参数说明，包括每个参数的作                  // 用、取值说明及参数间关系。  Output:         // 对输出参数的说明。  Return:         // 函数返回值的说明  Others:         // 其它说明*************************************************/

  最好的习惯：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的

一致性

代码注释原则:
 1：避免在一行代码或表达式的中间插入注释。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

 2：通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码

成为自注释的。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

 3：在代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助

读者理解代码，防止没必要的重复注释信息。

示例：如下注释意义不大。

/* if receive_flag is TRUE */if (receive_flag)而如下的注释则给出了额外有用的信息。 /* if mtp receive a message from links */if (receive_flag)

4：在程序块的结束行右方加注释标记，以表明某程序块的结束。

说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。

示例：参见如下例子。

if (...){    // program code    while (index < MAX_INDEX)    {        // program code    } /* end of while (index < MAX_INDEX) */ // 指明该条while语句结束} /* end of  if (...)*/ // 指明是哪条if语句结束

5：注释格式尽量统一，建议使用"/* …… */"。
6：注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用

中文，除非能用非常流利准确的英文表达。

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文（自己的母语）。

注释总结；
  1.一目了然的情况不写注释。记得刚进入软件开发行业的时候，日本客户的编码规约上就写着，当有

if、while、for的时候，一定要写明判断和循环的原因，那时幼稚的我一定会有这样的代码：这不是一句废话吗？但凡是个程序员都会知道这段代码是在做什么，可是我却写了很多年，回想一下真是傻的要命，这简直是在浪费键盘！

2.错误的注释还不如没有注释。很多时候人们会复制别人的代码，或者是被别人复制，复制的过程中，很容易忘记修改成符合自己的注释，记得有一次客户发邮件质问我们，为什么注释和代码不符，哦！那是抄袭的，忘记改了。还有一次客户的正式环境险些宕机，找到了问题SQL，发现此问题SQL上有段注释，-- 某年某月某日 某某某 修改，哈哈，貌似问题SQL的作者被抓到了，可是事实是这段是被另外一个人copy去的，冤枉死了～大晴天都可以下雪了！所以对复制来的代码中的注释一定要慎重啊。

3.对难以理解的代码进行注释。有些处理可能会很复杂，如果不记录下来可能自己都不会再记得，别人再看的时候也会非常麻烦，这里可以简单描述一下，切忌不可像写作文一样，反而让人更加迷惑。

4.不得不写注释的地方有待重构。复杂而又难以理解的代码我想都是有重构的必要的，把复杂的东西拆成若干个函数，各执其责，再复杂的代码也可以变的简单，我想，都变的很简单的时候，也就没有必要解释复杂逻辑了吧。

5.对类、函数、函数的形参进行注释。要快速知道你的程序的整体结构，除了类和函数的合理命名外，就是对类和函数进行合理的说明，我想，如果命名上已经贴切的不能再贴切了，那不写注释也无所谓了吧，但写上也是个很不错的想法。

6.努力写出自解代码。自解代码顾名思义，就是不用注释就可以很好的明白代码的含义，写出能让人容易懂的代码，比不得不写注释来解释的代码优秀的多。
总结：不写注释就可以看懂的代码，才是优秀的代码。

总结：
　　注释不仅仅能够增强代码的可读性，而且写注释的过程是一个思考代码功能的过

程，与代码比起来，寥寥几句注释更能够将功能抽象描述出来。从反面角度来说，如果一段代码的注释很难写，也就证明了该段代码所要实现的功能比较混乱，该段代码也就需要重写了。

　PS：注释作为一种引导思维的手段，应该写在代码前，而不是代码后。
 

 引用大师级的话： 　　

　　　　　　　　　　　　　最差的代码，没有注释
                      凑合用的代码，随意注释
                      合格的代码，注释和代码一致，并有助于代码的理解和维护
                      优良的代码，只做必要的注释