VC开发注释规范文档.docVIP

VC开发注释规范文档  目录 1 概述 3 2 目的 3 3 注释规范定义 3 3.1 总体定义 3 3.1.1 定义注释块 3 3.1.2 代码注释 4 3.2 文件注释块 4 3.3 类注释块 5 3.4 类成员变量、全局变量注释块 5 3.5 枚举、结构类型注释块 5 3.6 类成员方法、函数注释块 6 3.7 项目注释块 7 3.8 模块注释块 8 4 附录1：VS2008注释工具宏使用教程 10 4.1 安装VS2008注释工具宏 10 4.2 VS2008注释工具宏方法说明 11 4.2.1 BriefDescription 11 4.2.2 ClassDescription 11 4.2.3 DetailDescription 12 4.2.4 FileDescription 12 4.2.5 FunctionDescription 12 4.2.6 FunctionDescriptionFull 12 4.2.7 MainpageDescription 13 4.2.8 MemberDescription 13 4.2.9 ModuleDescription 13 4.2.10 ModuleDescriptionFull 13 概述 本文对VC开发代码编写过程中源文件的注释进行定义，包括注释的内容、格式及对应的条件等。VC开发过程必须按照本规范进行相应的注释编写。 目的 增强源代码的可阅读性、结构性，方便代码阅读者对源代码的阅读和理解。 为源代码文档的制作及生成奠定基础。 注释规范定义 总体定义 定义注释块 对于本章节中定义的注释块使用QT风格的注释格式，以“/*!”开始并以“*/”结束。如下所示： 特殊注释块中包含特定的标记，标记格式为：“@标记名称 标记内容”。具体的标记定义由各特殊注释块定义。 代码注释 对于代码的注释，如对程序中一个需要概括性说明或不易理解或易理解错的地方进行描述的注释等。使用C++注释行风格进行注释，即以“//”开头的一行注释。注释应与其描述的代码相近，对代码的注释统一放在其上方，避免在一行代码或表达式中间使用注释。上方注释与其上面的代码用空行隔开（较紧凑的代码除外）。如： 文件注释块 文件注释块对源代码文件进行注释，包括头文件（*.h）、C++文件（*.cpp）或C文件（*.c）。文件注释块置于对应文件的开头，包括文件名（@file）、文件简要说明（@brief）、作者（@author）、创建日期（@date）和版本号（@version）5个标记。如下所示： 类注释块 类注释块对已定义的类进行描述，位于对应类的定义上方。类注释块包括类名称（@class）、类简要说明（@brief）2个标记以及该类的详细描述，类的详细描述与@brief标记之间空一行。如下所示： 类成员变量、全局变量注释块 该注释块对类 / 枚举 / 结构的成员变量、全局变量以及使用typedef进行定义的类型进行描述，，位于对应变量定义的右方。注释块格式为“/*! 描述 */”。如下所示： 枚举、结构类型注释块 该注释块对枚举和结构进行描述，，位于对应枚举 / 结构定义的上方。注释块包括简要说明（@brief）标记以及可选的详细描述，若存在详细描述，详细描述与@brief标记之间空一行。如下所示： 类成员方法、函数注释块 该注释块对类的成员方法或全局函数进行描述，位于对应方法 / 函数的定义上方。 类成员方法、函数注释块包含以下内容： 简要说明标记（@brief），内容为方法 / 函数的简要说明。 详细描述，详细描述与@brief标记之间空一行。 若干个参数描述标记（@param），数量与该方法的输入参数个数相同。格式为：“@param 参数名称 参数说明”。 异常描述标记（@exception），对该方法抛出的异常进行描述，可省略。 警告标记（@warning），对调用方法需要注意的地方进行描述，可省略。 前置条件标记（@pre），描述执行方法的前置条件，比如对输入参数的要求等，可省略。 后置条件标记（@post），描述执行方法的后置条件，比如对系统状态的影响或返回参数的结果预期等，可省略。 增加日期标记（@since），对于新增的方法，描述什么时候增加该方法及增加该方法的意图。可省略。 TODO标记（@todo），对该方法将要做的事情进行描述，用于比较关键的方法。 缺陷标记（@bug），对该方法存在的缺陷进行描述。若存在已知的缺陷，需要定义该标记，否则省略。 返回值标记（@return），描述该方法的返回值，格式为：“@return 返回值类型 返回值描述”。若返回值为void类型，则省略该标记。 以下是一个最基本的类成