VC开发注释规范文档.doc

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.3DetailDescription124.2.4FileDescription124.2.5FunctionDescription124.2.6FunctionDescriptionFull124.2.7MainpageDescription134.2.8MemberDescription134.2.9ModuleDescription134.2.10ModuleDescriptionFull131 概述本文对VC开发代码编写过程中源文件的注释进行定义，包括注释的内容、格式及对应的条件等。VC开发过程必须按照本规范进行相应的注释编写。2 目的l 增强源代码的可阅读性、结构性，方便代码阅读者对源代码的阅读和理解。l 为源代码文档的制作及生成奠定基础。3 注释规范定义3.1 总体定义3.1.1 定义注释块对于本章节中定义的注释块使用QT风格的注释格式，以“/*!”开始并以“*/”结束。如下所示：/*! * 一个注释块 */特殊注释块中包含特定的标记，标记格式为：“标记名称 ”。具体的标记定义由各特殊注释块定义。3.1.2 代码注释对于代码的注释，如对程序中一个需要概括性说明或不易理解或易理解错的地方进行描述的注释等。使用C+注释行风格进行注释，即以“/”开头的一行注释。注释应与其描述的代码相近，对代码的注释统一放在其上方，避免在一行代码或表达式中间使用注释。上方注释与其上面的代码用空行隔开（较紧凑的代码除外）。如： if (mSocket = INVALID_SOCKET) return; / shutdown SD_SEND shutdown(mSocket, 1);3.2 文件注释块文件注释块对源代码文件进行注释，包括头文件（*.h）、C+文件（*.cpp）或C文件（*.c）。文件注释块置于对应文件的开头，包括文件名（file）、文件简要说明（brief）、作者（author）、创建日期（date）和版本号（version）5个标记。如下所示：/*! * file NewClient.h * brief 文件简要说明 * author Limnk * date 2011-06-23 * version 1.0 */3.3 类注释块类注释块对已定义的类进行描述，位于对应类的定义上方。类注释块包括类名称（class）、类简要说明（brief）2个标记以及该类的详细描述，类的详细描述与brief标记之间空一行。如下所示：/*! * class CNewClientApp * brief 动态库APP类 * * NewClient动态库的APP类，包含动态库加载时的初始化操作等. */class CNewClientApp : public CWinApp3.4 类成员变量、全局变量注释块该注释块对类 / 枚举 / 结构的成员变量、全局变量以及使用typedef进行定义的类型进行描述，位于对应变量定义的右方。注释块格式为“/*! 描述 */”。如下所示：pjsua_transport_idm_udpid;/*! UDP transport 的ID */3.5 枚举、结构类型注释块该注释块对枚举和结构进行描述，位于对应枚举 / 结构定义的上方。注释块包括简要说明（brief）标记以及可选的详细描述，若存在详细描述，详细描述与brief标记之间空一行。如下所示：/*! brief Request results */enum MCResult MCERR_OK = 0,/*! Success */ MCERR_NOREPLY = 1,/*! no reply requested) */;3.6 类成员方法、函数注释块该注释块对类的成员方法或全局函数进行描述，位于对应方法 / 函数的定义上方。类成员方法、函数注释块包含以下内容：a) 简要说明标记（brief），内容为方法 / 函数的简要说明。b) 详细描述，详细描述与brief标记之间空一行。c) 若干个参数描述标记（param），数量与该方法的输入参数个数相同。格式为：“param 参数名称 参数说明”。d) 异常描述标记（exception），对该方法抛出的异常进行描述，可省略。e) 警告标记（warning），对调用方法需要注意的地方进行描述，可省略。f) 前置条件标记（pre），描述执行方法的前置条件，比如对输入参数的要求等，可省略。g) 后置条件标记（post），描述执行方法的后置条件，比如对系统状态的影响或返回参数的结果预期等，可省略。h) 增加日期标记（since），对于新增的方法，描述什么时候增加该方法及增加该方法的意图。可省略。i) TODO标记（todo），对该方法将要做的事情进行描述，用于比较关键的方法。j) 缺陷标记（bug），对该方法存在的缺陷进行描述。若存在已知的缺陷，需要定义该标记，否则省略。k) 返回值标记（return），描述该方法的返回值，格式为：“return 返回值类型 返回值描述”。若返回值为void类型，则省略该标记。以下是一个最基本的类成员方法注释块：/*! * brief DestoryClient * * 销毁一个客户端对象 * param nKey 要销毁的客户端对象的KEY * return BOOL 成功返回TRUE，否则FALSE */BOOL DestoryClient(UINT nKey);3.7 项目注释块项目注释块该用于对项目进行描述，每个项目只出现一次。对于MFC生成的项目，将该注释块置于项目APP类定义的头文件中。对于其它类型的项目，置于定义项目入口函数的文件中。对于无入口函数的项目，比如静态库项目，置于较关键且不会被外部项目引用的文件中。项目注释块以“/*! mainpage”开头，以“*/”结束。包含项目描述、及功能描述、用法描述、注意事项4个描述章节。项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容。功能描述章节列举该项目的主要功能。用法描述章节列举该项目的主要使用方法，主要针对动态库、静态库等会被其它项目使用的项目。对于其它类型的项目，该章节可省略。注意事项章节描述该项目的注意事项、依赖项目等相关信息。以下是一个项目注释块：/*! mainpage * * * Project NewClient * Author 作者 * Source 代码库目录 * * * 项目详细描述 * * section features 功能描述 * * - 功能描述1 * - 功能描述2 * * section usage 用法描述 * * * 使用步骤1 * 使用步骤1 的样例 * 使用步骤2 * 使用步骤2 的样例 * * * section notes 注意事项 * 注意事项描述 * */3.8 模块注释块模块注释块该用于将一系列相关功能的类、函数、枚举、结构等归入一个模块并进行描述。模块注释块包括模块起始注释块及模块结束注释块两个部分。模块起始注释块包含模块名称标记（defgroup）、模块简介标记（brief）、模块详细描述及模块起始标记（）4个部份。如下所示：/*!* defgroup 模块名称* brief 模块简介* * 模块的详细描述* */模块结束注释用于结束一模块描述定义，格式为“/* */”。与模块起始注释块成对出现。包含在模块起始注释块与结束注释块之间的所有内容将归入该模块。若需要将其它文件中定义的内容归入一个已定义的模块，可使用简略的模块起始注释块与结束注释块括起需要归入该模块的内容。简略的模块起始注释块仅包含模块名称标记（defgroup）。如下所示：/*!* defgroup 模块名称* */class CIMCControllerpublic:CIMCController();virtual CIMCController();/* */4 附录1：VS2008注释工具宏使用教程4.1 安装VS2008注释工具宏1) 从 ftp:/dev35/VC2008Macro.vsmacros 下载注释工具宏文件：VC2008Macro.vsmacros 。2) 在VS2008环境中选择菜单：工具宏加载宏项目，如下图所示：3) 选择第1步下载的VC2008Macro.vsmacros文件，点击添加。4) 加载成功后，可在宏资源管理器看到添加的项，如下图所示：5) 可使用“自定义”功能将以上方法添加到工具栏，此步骤非必要步骤。4.2 VS2008注释工具宏方法说明4.2.1 BriefDescription生成一个简单的注释块：“/*! brief 简要说明 */”，一般用于枚举、结构类型的描述。4.2.2 ClassDescription生成一个类的注释块。选中类的定义文本后双击此方法可根据类的定义自动生成注释块。4.2.3 DetailDescription生成一个包含详细描述的注释块：/*! * brief 简要说明 * * 详细描述. */4.2.4 FileDescription在文件头生成一个文件注释块。4.2.5 FunctionDescription生成一个基本的方法 / 函数注释块，选中方法定义（如下图所示）后双击此方法可自动生成。4.2.6 FunctionDescript