C语言注释规范.docVIP

C语言注释规范 注释原则 同一软件项目开发中，尽量保持代码注释规范和统一。 注释方便了代码的阅读和维护。 边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。 注释 要 简洁明确，不要出现形容词。 对于写的好的注释，我们将是第一个受益者。 大型软件开发中，通过别人的注释可以快速知道他人所写函数的功能，返回值，参数的使用。 文件头部的注释 示例： /****************************************************** * Program Assignment : 该文件的作用 * Author: 作者 * Date: 2013/8/6 14:34 * Description: 该文件的描述 *****************************************************/ /******************************************************* * Source code in : 源代码的路径 * Function List: * initLinear 初始化线性表 * destoryLinear 释放线性表申请的空间 * isLinearEmpty 判断线性表是否为空 * isLinearFull 判断线性表是否为满 * getLinearElementValue 取得下标为index的元素的值 *******************************************************/ 注意：这个函数列表可以快速查询到我们想要了解的函数。 结构体，全局变量等的注释 示例： typedef POLYNOMIAL USER_TYPE; /* 新的数据类型的描述 */ int a; /* 全局变量的作用 */ /* 说明结构体的功能 */ typedef struct LINEAR { USER_TYPE *data; /* 每个成员的意义(作用) */ int maxRoom; /* 每个成员的意义(作用) */ int elementCount; /* 每个成员的意义(作用) */ }LINEAR; 函数的注释 在逻辑性较强的的地方加入注释，以便其他人的理解，在一定的程度上排除bug。 示例： /******************************************************* * Function Name: getLinearElementIndex * Purpose: 取得元素的index值 * Params : * @LINEAR linear 线性表实例 * @USER_TYPE var 类型为USER_TYPE的实例 * @int (*)() cmp 提供接口，让用户定义具体比较函数 * Return: int 返回元素的index值 * Limitation: 如果返回-1，则代表不存在var的元素 *******************************************************/ int getLinearElementIndex(LINEAR linear, USER_TYPE var, int (*cmp)()) { /* * 如果逻辑太过复杂，这里写明 该算法的过程和思路。 */ boolean found = FALSE; int i; for(i = 0; i linear.elementCount !found; i++) if(cmp(linear.data[i], var) == 0) found = TRUE; if(i = linear.elementCount) i = NOT_FOUND; return i; }