VC开发注释规范文档.docx
《VC开发注释规范文档.docx》由会员分享，可在线阅读，更多相关《VC开发注释规范文档.docx（14页珍藏版）》请在冰豆网上搜索。
VC开发注释规范文档
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.2VS2008注释工具宏方法说明11
4.2.1BriefDescription11
4.2.2ClassDescription11
4.2.3DetailDescription12
4.2.4FileDescription12
4.2.5FunctionDescription12
4.2.6FunctionDescriptionFull12
4.2.7MainpageDescription13
4.2.8MemberDescription13
4.2.9ModuleDescription13
4.2.10ModuleDescriptionFull13
概述
本文对VC开发代码编写过程中源文件的注释进行定义，包括注释的内容、格式及对应的条件等。
VC开发过程必须按照本规范进行相应的注释编写。
1目的
●增强源代码的可阅读性、结构性，方便代码阅读者对源代码的阅读和理解。
●为源代码文档的制作及生成奠定基础。
2注释规范定义
2.1总体定义
2.1.1定义注释块
对于本章节中定义的注释块使用QT风格的注释格式，以“/*!
”开始并以“*/”结束。
如下所示：
/*!
*一个注释块
*/
特殊注释块中包含特定的标记，标记格式为：
“@标记名称<标记内容>”。
具体的标记定义由各特殊注释块定义。
2.1.2代码注释
对于代码的注释，如对程序中一个需要概括性说明或不易理解或易理解错的地方进行描述的注释等。
使用C++注释行风格进行注释，即以“//”开头的一行注释。
注释应与其描述的代码相近，对代码的注释统一放在其上方，避免在一行代码或表达式中间使用注释。
上方注释与其上面的代码用空行隔开（较紧凑的代码除外）。
如：
if（mSocket==INVALID_SOCKET）{
return;
}
//shutdownSD_SEND
shutdown（mSocket,1）;
2.2文件注释块
文件注释块对源代码文件进行注释，包括头文件（*.h）、C++文件（*.cpp）或C文件（*.c）。
文件注释块置于对应文件的开头，包括文件名（@file）、文件简要说明（@brief）、作者（@author）、创建日期（@date）和版本号（@version）5个标记。
如下所示：
/*!
*@fileNewClient.h
*@brief文件简要说明
*@authorLimnk
*@date2011-06-23
*@version1.0
*/
2.3类注释块
类注释块对已定义的类进行描述，位于对应类的定义上方。
类注释块包括类名称（
@class）、类简要说明（@brief）2个标记以及该类的详细描述，类的详细描述与@brief标记之间空一行。
如下所示：
/*!
*@classCNewClientApp
*@brief动态库APP类
*
*NewClient动态库的APP类，包含动态库加载时的初始化操作等.
*/
classCNewClientApp:
publicCWinApp
{
2.4类成员变量、全局变量注释块
该注释块对类/枚举/结构的成员变量、全局变量以及使用typedef进行定义的类型进行描述，，位于对应变量定义的右方。
注释块格式为“/*!
<描述*/”。
如下所示：
pjsua_transport_idm_udpid;/*!
2.5枚举、结构类型注释块
该注释块对枚举和结构进行描述，，位于对应枚举/结构定义的上方。
注释块包括简要说明（@brief）标记以及可选的详细描述，若存在详细描述，详细描述与@brief标记之间空一行。
如下所示：
/*!
@briefRequestresults*/
enumMCResult{
MCERR_OK=0,/*!
MCERR_NOREPLY=1,/*!
};
2.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类型，则省略该标记。
以下是一个最基本的类成员方法注释块：
/*!
*@briefDestoryClient
*
*销毁一个客户端对象
*@paramnKey要销毁的客户端对象的KEY
*@returnBOOL成功返回TRUE，否则FALSE
*/
BOOLDestoryClient（UINTnKey）;
2.7项目注释块
项目注释块该用于对项目进行描述，每个项目只出现一次。
对于MFC生成的项目，将该注释块置于项目APP类定义的头文件中。
对于其它类型的项目，置于定义项目入口函数的文件中。
对于无入口函数的项目，比如静态库项目，置于较关键且不会被外部项目引用的文件中。
项目注释块以“/*!
@mainpage”开头，以“*/”结束。
包含项目描述、及功能描述、用法描述、注意事项4个描述章节。
项目描述章节描述项目名称、作者、代码库目录、项目详细描述4项内容。
功能描述章节列举该项目的主要功能。
用法描述章节列举该项目的主要使用方法，主要针对动态库、静态库等会被其它项目使用的项目。
对于其它类型的项目，该章节可省略。
注意事项章节描述该项目的注意事项、依赖项目等相关信息。
以下是一个项目注释块：
/*!
@mainpage
*
*
*
| Project | NewClient * |
|---|
| Author | [作者] * |
|---|
| Source | [代码库目录] * |
|---|
*
*[项目详细描述]
*
*@sectionfeatures功能描述
*
*-[功能描述1]
*-[功能描述2]
*
*@sectionusage用法描述
*
*
*
[使用步骤1]
*
[使用步骤1的样例]
*
[使用步骤2]*
[使用步骤2的样例]
*
*
*@sectionnotes注意事项
*[注意事项描述]
*
*/
2.8模块注释块
模块注释块该用于将一系列相关功能的类、函数、枚举、结构等归入一个模块并进行描述。
模块注释块包括模块起始注释块及模块结束注释块两个部分。
模块起始注释块包含模块名称标记（@defgroup）、模块简介标记（@brief）、模块详细描述及模块起始标记（@{）4个部份。
如下所示：
/*!
*@defgroup模块名称
*@brief模块简介
*
*模块的详细描述
*@{
*/
模块结束注释用于结束一模块描述定义，格式为“/**@}*/”。
与模块起始注释块成对出现。
包含在模块起始注释块与结束注释块之间的所有内容将归入该模块。
若需要将其它文件中定义的内容归入一个已定义的模块，可使用简略的模块起始注释块与结束注释块括起需要归入该模块的内容。
简略的模块起始注释块仅包含模块名称标记（@defgroup）。
如下所示：
/*!
*@defgroup模块名称
*@{
*/
classCIMCController
{
public:
CIMCController（）;
virtual~CIMCController（）;
};
/**@}*/
3附录1：
VS2008注释工具宏使用教程
3.1安装VS2008注释工具宏
1）从ftp:
//dev@172.18.8.135/VC2008Macro.vsmacros下载注释工具宏文件：
VC2008Macro.vsmacros。
2）在VS2008环境中选择菜单：
工具—>宏—>加载宏项目，如下图所示：
3）选择第1步下载的VC2008Macro.vsmacros文件，点击添加。
4）加载成功后，可在宏资源管理器看到添加的项，如下图所示：
5）可使用“自定义”功能将以上方法添加到工具栏，此步骤非必要步骤。
3.2VS2008注释工具宏方法说明
3.2.1BriefDescription
生成一个简单的注释块：
“/*!
@brief[简要说明]*/”，一般用于枚举、结构类型的描述。
3.2.2ClassDescription
生成一个类的注释块。
选中类的定义文本后双击此方法可根据类的定义自动生成注释块。
3.2.3DetailDescription
生成一个包含详细描述的注释块：
/*!
*@brief[简要说明]
*
*[详细描述].
*/
3.2.4FileDescription
在文件头生成一个文件注释块。
3.2.5FunctionDescription
生成一个基本的方法/函数注释块，选中方法定义（如下图所示）后双击此方法可自动生成。
3.2.6FunctionDescriptionFull
生成一个包含全标记的方法/函数注释块，与FunctionDescription类似。
3.2.7MainpageDescription
生成一个项目注释块。
3.2.8MemberDescription
生成一个变量的注释块
3.2.9ModuleDescription
生成一对简略的模块起始注释块与模块结束注释块类。
3.2.10ModuleDescriptionFull
生成一对模块起始注释块与模块结束注释块类。
.
升级会员 