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

江苏沿海CPS研究院 编号：YCTC_S2C_01  PAGE 12 项目编号：AN_DX_012 第三届中国大学生服务外包创新应用大赛 盐城师范学院参赛团队(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注释原则 有助于对程序的阅读理解,说明程序在做什么,解释代码的目的、功能和采用的方法。 一般情况源程序有效注释量在50%左右。注释语言必须准确、易懂、简洁。边写代码边注释,修改代码同时修改相应的注释,不再有用的注释要删除。 2.2源文件头部注释规范 文件注释必须说明文件名、函数功能、创建人、创建日期、版本信息等相关信息。修改文件代码时,应在文件注释中记录修改日期、修改人员,并简要说明此次修改的目的。所有修改记录必须保持完整。文件注释放在文件顶端,用/*……*/格式包含。注释文本每行缩进一个制表符;每个注释文本分项名称应对齐。： /*********************************************************** *@Filename SHT1X.c*@author XXXX*@Revision: V1.0@Revised: 2012.7.22（XXX改XXX） *@brief: SHT1X系列芯片驱动文件***********************************************************/ 2.3数据变量注释 同一类型的标识符应集中定义,并在定义之前一行对其共性加以统一注释。对单个标识符的注释加在定义语句的行尾。全局变量一定要有详细的注释,包括其功能、取值范围、哪些函数或过程存取它以及存取时的注意事项等。注释用//…的格式。 2.4函数注释 函数头部注释应包括函数名称（@fu）、函数描述(@brief)、入口参数(@param)、出口参数(@return)等内容。如有必要还可增加作者、创建日期、修改记录(备注)等相关项目。函数头部注释放在每个函数的顶端,用/*……*/的格式包含。其中函数名称应简写为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)。每个文档注释都会被置于注释定界符/*...*/之中，一个注释对应一个成员或方法。该注释应位于声明之前： /*********************************************************** * @