vc开发注释规范文档

《vc开发注释规范文档》由会员上传分享，免费在线阅读，更多相关内容在行业资料-天天文库。

1、VC开发注释规范文档目录1概述32目的33注释规范定义33.1总体定义33.1.1定义注释块33.1.2代码注释43.2文件注释块43.3类注释块53.4类成员变量、全局变量注释块53.5枚举、结构类型注释块53.6类成员方法、函数注释块63.7项目注释块73.8模块注释块84附录1：VS2008注释工具宏使用教程104.1安装VS2008注释工具宏104.2VS2008注释工具宏方法说明114.2.1BriefDescription114.2.2ClassDescription114.2.3DetailDescription12

2、4.2.4FileDescription124.2.5FunctionDescription124.2.6FunctionDescriptionFull124.2.7MainpageDescription134.2.8MemberDescription134.2.9ModuleDescription134.2.10ModuleDescriptionFull13概述本文对VC开发代码编写过程中源文件的注释进行定义，包括注释的内容、格式及对应的条件等。VC开发过程必须按照本规范进行相应的注释编写。1目的l增强源代码的可阅读性、结构性，

3、方便代码阅读者对源代码的阅读和理解。l为源代码文档的制作及生成奠定基础。2注释规范定义2.1总体定义2.1.1定义注释块对于本章节中定义的注释块使用QT风格的注释格式，以“/*!”开始并以“*/”结束。如下所示：/*!*一个注释块*/特殊注释块中包含特定的标记，标记格式为：“@标记名称<标记内容>”。具体的标记定义由各特殊注释块定义。1.1.1代码注释对于代码的注释，如对程序中一个需要概括性说明或不易理解或易理解错的地方进行描述的注释等。使用C++注释行风格进行注释，即以“//”开头的一行注释。注释应与其描述的代码相近，对代码的注

4、释统一放在其上方，避免在一行代码或表达式中间使用注释。上方注释与其上面的代码用空行隔开（较紧凑的代码除外）。如：if(mSocket==INVALID_SOCKET){return;}//shutdownSD_SENDshutdown(mSocket,1);1.2文件注释块文件注释块对源代码文件进行注释，包括头文件（*.h）、C++文件（*.cpp）或C文件（*.c）。文件注释块置于对应文件的开头，包括文件名（@file）、文件简要说明（@brief）、作者（@author）、创建日期（@date）和版本号（@version）5个

5、标记。如下所示：/*!*@fileNewClient.h*@brief文件简要说明*@authorLimnk*@date2011-06-23*@version1.0*/1.1类注释块类注释块对已定义的类进行描述，位于对应类的定义上方。类注释块包括类名称（@class）、类简要说明（@brief）2个标记以及该类的详细描述，类的详细描述与@brief标记之间空一行。如下所示：/*!*@classCNewClientApp*@brief动态库APP类**NewClient动态库的APP类，包含动态库加载时的初始化操作等.*/class

6、CNewClientApp:publicCWinApp{1.2类成员变量、全局变量注释块该注释块对类/枚举/结构的成员变量、全局变量以及使用typedef进行定义的类型进行描述，，位于对应变量定义的右方。注释块格式为“/*!<描述*/”。如下所示：pjsua_transport_idm_udpid;/*!

7、一行。如下所示：/*!@briefRequestresults*/enumMCResult{MCERR_OK=0,/*!

8、数相同。格式为：“@param参数名称参数说明”。d)异常描述标记（@exception），对该方法抛出的异常进行描述，可省略。e)警告标记（@warning），对调用方法需要注意的地方进行描述，可省略。f)前置条件标记（@pre），描述执行方法的