者、创建日期、功能描述、 2.5 函数头部应进行注释,列出:函数名称、作者、创建日期、功能描述、输入参 输出参数、返回值、调用关系(函数、 、修改日志等。 、修改日志等 数、输出参数、返回值、调用关系(函数、表) 修改日志等。
示例:下面这段函数的注释比较标准。 //////////////////////////////////////////////////////////////// //函数名称: //作者: (此项仅用于全局函数或非文件的创建者编写的函数) //创建日期: (此项仅用于全局函数或非文件的创建者编
写的函数) //功能描述: //输入参数: //输出参数: //返回值: //被本函数调用的函数清单: //调用本函数的函数清单: //被访问的表: (此项仅用于牵扯到数据库操作的函数) //被修改的表: (此项仅用于牵扯到数据库操作的函数) //备注: //修改日志: // // // // // 1. 修改日期: 修改者: 修改原因: 修改内容: 2. ...
////////////////////////////////////////////////////////////////
边写代码边注释, 修改代码同时修改相应的注释, 以保证注释与代码的一致性。 2.6 边写代码边注释, 修改代码同时修改相应的注释, 以保证注释与代码的一致性。 不再有用的注释要删除。注释的内容要清楚、明了,含义准确, 不再有用的注释要删除。注释的内容要清楚、明了,含义准确,防止注释二义 避免在注释中使用缩写,特别是非常用缩写。 性。避免在注释中使用缩写,特别是非
常用缩写。 注释应与其描述的代码相近 对代码的注释应放在其上方或右方( 代码相近, 2.7 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句 的注释)相邻位置,不可放在下面, 的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔 开。
//初始化保存累加和的临时变量为 0 int sum = 0;
//累加求和
第 5页
武汉华工赛百数据系统有限公司 Central-China Cyber Data System Co., Ltd.
for (count = 0; count < num; count++) { sum += data[count]; }
对于所有有物理含义的变量、常量,如果其命名不是充分自注释的, 2.8 对于所有有物理含义的变量、常量,如果其命名不是充分自注释的,在声明时 都必须加以注释,说明其物理含义。变量、常量、 都必须加以注释,说明其物理含义。变量、常量、宏的注释应放在其上方相邻 位置或右方。 位置或右方。
//圆弧的起点坐标 CPoint m_ptBegin;
//圆弧的终点坐标 CPoint m_ptEnd;
数据结构声明(包括数组、 结构、 枚举等) 如果其命名不是充分自注释的, 如果其命名不是充分自注释的, 2.9 数据结构声明(包括数组、 结构、 、 类 枚举等), 必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面; 必须加以注释。对数据结构的注释应放在其上方相邻位置,不可放在下面;对 结构中的每个域的注释放在此域的右方。 结构中的每个域的注释放在此域的右方。
//选择工具中出现的几种状态 typedef enum tagSTATUS { ISMOVE, ISROTATE, ISRESIZE, NOSELECT } STATUS; //图形处于移动状态 //图形处于旋转状态 //图形处于放大状态 //图形处于没有选择状态
2.10 全局变量要有较详细的注释,包括对其功能、取值范围、哪些函数或过程存取 全局变量要
有较详细的注释,包括对其功能、取值范围、 它以及存取时注意事项等的说明。 它以及存取时注意事项等的说明。 注释与所描述内容进行同样的缩排。将注释与其上面的代码用空行隔开。 2.11 注释与所描述内容进行同样的缩排。将注释与其上面的代码用空行隔开。
//圆弧的起点坐标 CPoint m_ptBegin;
//圆弧的终点坐标 CPoint m_ptEnd;
避免在一行代码或表达式的中间插入注释。在代码的功能、 2.