代码注释（Code comments）

标签：

/头文件的头注释
/*************************************************
  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:         // 其它说明
*************************************************/

/************************************************************
  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)

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

示例：参见如下例子。

if (...)
{
    // program code

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

代码注释（Code comments）

标签：

原文地址：http://blog.csdn.net/u013067756/article/details/44277715