01-软件编码和命名规范.docVIP

第三届中国大学生服务外包创新应用大赛 盐城师范学院参赛团队(ITGroup) 下位机软件编码和命名规范 2012.7 文档修订记录 版本 完成人 修改内容 审核 批准 时间 V1.0 徐裕峰 创建文档 全体 2012-6-3 1注释常用标签说明 @author 表示作者信息 @brief 用于function的批注中，后面为function的简易说明。 @param 格式为 @param [in,intout,out] arg_name -参数说明 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明。 @return 后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。 @Revision 用于说明文件版本号 @ Revised 用于说明修改内容、时间和修改者 格式为 20xx.x.x(XXX对XXXX进行修改) 2 注释规范 2.1注释原则 有助于对程序的阅读理解,说明程序在做什么,解释代码的目的、功能和采用的方法。 一般情况源程序有效注释量在%左右。注释语言必须准确、易懂、简洁。边写代码边注释,修改代码同时修改相应的注释,不再有用的注释要删除。 文件注释必须说明文件名、函数功能、创建人、创建日期、版本信息等相关信息。修改文件代码时,应在文件注释中记录修改日期、修改人员,并简要说明此次修改的目的。所有修改记录必须保持完整。文件注释放在文件顶端,用/*……*/格式包含。注释文本每行缩进;每个注释文本分项名称应对齐。/*********************************************************** *@Filename SHT1X.c*@author XXXX*@Revision: V1.0@Revised: 2012.7.22（XXX改XXX） *@brief: SHT1X系列芯片驱动文件***********************************************************/ 2.3数据变量注释 同一类型的标识符应集中定义,并在定义之前一行对其共性加以统一注释。对单个标识符的注释加在定义语句的行尾。全局变量一定要有详细的注释,包括其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等注释用//…的格式函数头部注释应包括函数名称、函数、入口参数、出口参数等内容。如有必要还可增加作者、创建日期、修改记录(备注)等相关项目。函数头部注释放在每个函数的顶端,用/*……*/的格式包含。其中函数名称应简写为FunctionName,不加入、出口参数等信息。/*********************************************************** * @fn MT_AfDataConfirm * * @brief AD数据处理过程 * * @param pBuf – 指向接收数据缓冲区物理地址的指针 * * @return void ***********************************************************/ void MT_AfDataConfirm(afDataConfirm_t *pMsg) { uint8 retArray[3]; retArray[0] = pMsg-hdr.status; retArray[1] = pMsg-endpoint; retArray[2] = pMsg-transID; /* 创建和回传信息 */ MT_BuildAndSendZToolResponse(((uint8)MT_RPC_CMD_AREQ | (uint8)MT_RPC_SYS_AF), MT_AF_DATA_CONFIRM, 3, retArray); } 2.4.1无参数型注释 文档注释描述C，方法，以及字段(field)。每个文档注释都会被置于注释定界符/*...*/之中，一个注释对应一个成员或方法。该注释应位于声明之前： /*********************************************************** * @fn MT_Init * * @brief Initialize MT. * * @return void ***********************************************************/ void MT_Init() { debug