doxygen标准VC注释(转)
C++ 程序文档生成器介绍(doxygen)
程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。
好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：
1. 模块定义（单独显示一页）
/*
* @defgroup 模块名模块的说明文字
* @{
*/
... 定义的内容 ...
/** @} */ // 模块结尾
2. 分组定义（在一页内分组显示）
/*
* @name 分组说明文字
* @{
*/
... 定义的内容 ...
/** @} */
3. 变量、宏定义、类型定义简要说明
/** 简要说明文字 */
#define FLOAT float
/** @brief 简要说明文字（在前面加 @brief 是标准格式） */
#define MIN_UINT 0
/*
* 分行的简要说明 \n
* 这是第二行的简要说明
*/
int b;
4. 函数说明
/*
* 简要的函数说明文字
* @param [in] param1 参数1说明
* @param [out] param2 参数2说明
* @return 返回值说明
*/
int func(int param1, int param2);
/*
* 打开文件 \n
* 文件打开成功后，必须使用 ::CloseFile 函数关闭。
* @param[in] file_name 文件名字符串
* @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成：
* - r 读取
* - w 可写
* - a 添加
* - t 文本模式(不能与 b 联用)
* - b 二进制模式(不能与 t 联用)
* @return 返回文件编号
* - -1 表示打开文件失败
* @note 文件打开成功后，必须使用 ::CloseFile 函数关闭
* @par 示例:
* @code
// 用文本只读方式打开文件
int f = OpenFile("d:\\test.txt", "rt");
* @endcode
* @see ::ReadFile ::WriteFile ::CloseFile
* @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
*/
int OpenFile(const char* file_name, const char* file_mode);
5. 枚举类型定义
/** 枚举常量 */
typedef enum TDayOfWeek
{
SUN = 0,/**< 星期天（注意，要以“<” 小于号开头） */ MON = 1,/**< 星期一 */
TUE = 2,/**< 星期二 */
WED = 3,/**< 星期三 */
THU = 4,/**< 星期四 */
FRI = 5,/**< 星期五 */
SAT = 6/**< 星期六 */
}
/** 定义类型 TEnumDayOfWeek */
TEnumDayOfWeek;
6.类的注释说明（实例）
----------------------------- Example Begin ---------------------------------
# 文件的注释格式
# 注释文件,格式: ///@file 文件名文件的简短注释.
///@file socket_c.h head file of class socket_c.
# 文件的详细注释.
///Define the interface of class socket_c.
# 普通注释,不会生成在文档中.
//$Id: socket_c.h 287 2004-06-28 06:20:41Z horin $
# 类的注释,格式: ///@brief 简短注释内容.
///@brief class of server socket.
class socket_c
{
private:
public:
# 函数的注释格式
# 函数的注释,格式: ///@brief 函数的简短注释.
///@brief handle the connections of clients.
# 参数注释,格式: ///@param 参数的简短注释.
///@param server the server ip address.
///@param serv_port the server #port.
# 返回值注释,格式: ///@return 返回值的简短注释.
///@return connected socketfd.
# 具体返回值的注释,格式: ///@retval 返回值该返回值的注释.
///@retval connfd on success.
///@retval 0 on EINTR - system call.
///@retval -1 on error.
# 参见...,格式: ///@see 参见的类/文件等.
///@see main_ppc.cpp
int accept_client(const int listenfd);
};
# 自定义类型的注释
///@brief structure of child process.
struct child_proc_s
{
# 行尾的注释,格式: ///< 注释内容.
pid_t child_pid; /// int child_pipefd; /// }; # 全局变量的注释,也可以采用上面的行尾格式进行注释. ///gloable variable for signal. pid_t g_pid = 0; ----------------------------- Example End --------------------------------- 7. 配置文件的生成与修改 Doxygen的功能强大,配置选项也十分多. 如果是命令行模式, 有些不便. 因此建议使用GUI的Doxywizard(可以从<开始>菜单中运行). 下面就对我个人认为比较重要的选项,并结合实例(生成html文档) 进行简单说明. 下面列出的一般是需要修改的,未列出的我采用缺省值. # Project选项 #--------------------------------------------------------------------------- # Staff_TPC是生成文档的项目名,会显示在文档中. PROJECT_NAME = Staff_TPC PROJECT_NUMBER = 1.0 # 项目版本号 # 生成文档的输出路径 OUTPUT_DIRECTORY = "f:/My Documents/cpp/horin/staff/" # 生成文档的语言,缺省是English,也可以是简体中文等. OUTPUT_LANGUAGE = English JA V ADOC_AUTOBRIEF = YES# 打开此选项. # Build 选项 #--------------------------------------------------------------------------- SHOW_INCLUDE_FILES = NO # 不显示所有包括的文件. # input 选项 #--------------------------------------------------------------------------- # 要生成文档的源文件的路径. 如果是一个目录,则是该目录下的所有文件; 当然,也可以 # 是具体的某个文件. INPUT = "f:/My Documents/cpp/horin/staff/tpc/" # 输入文件的匹配模式,下面是c / c++语言的设置. FILE_PATTERNS = *.c \ *.cpp \ *.h \ *.hpp RECURSIVE = YES # 需要递归处理子目录. # source browser选项 #--------------------------------------------------------------------------- # 如为SOURCE_BROWSER和INLINE_SOURCES都设置为YES, 则生成的文档中会包括源代码 # (即.cpp文件),这可以方便阅读时查看源代码. SOURCE_BROWSER = NO INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # 忽略普通的文档注释. REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES VERBA TIM_HEADERS = YES # HTML 选项 #--------------------------------------------------------------------------- GENERATE_HTML = YES # 需要生成html格式的文档. GENERATE_HTMLHELP = YES # 需要生成windows HTMLHELP格式的目录,以方便阅读. GENERATE_TREEVIEW = YES # 需要生成树视图,以方便阅读. # LaTeX 选项 #--------------------------------------------------------------------------- GENERATE_LATEX = NO # 不需要生成LaTeX输出. # dot 选项# 此选项是生成图形,建议(需要)安装graphviz. #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HA VE_DOT = YES # 已经安装graphviz.打开此选项. CLASS_GRAPH = YES # 生成类图 COLLABORATION_GRAPH = YES # 生成协作图 UML_LOOK = NO 在上面根据自己的需要对各个选项进行了配置,下面很重要的一步,就是把配置保存下来. 呵呵,这是大家最擅长的了. 可以命名配置文件为Doxygen-YourName.txt, 今后只需修改project和input选项,即可重用. 8. 项目符号标记 /* * A list of events: * - mouse events * -# mouse move event * -# mouse click event\n * More info about the click event. * -# mouse double click event * - keyboard events * -# key down event * -# key up event * * More text here. */ 结果为： A list of events: mouse events a.mouse move event b.mouse click event More info about the click event. c.mouse double click event keyboard events d.key down event e.key up event More text here. 代码示范： /* * @defgroup EXAMPLES 自动注释文档范例 * @author 沐枫 * @version 1.0 * @date 2004-2005 * @{ */ /* * @name 文件名常量 * @{ */ /** 日志文件名 */ #define LOG_FILENAME "d:\\log\\debug.log" /** 数据文件名 */ #define DATA_FILENAME "d:\\data\\detail.dat" /** 存档文件名 */ #define BAK_FILENAME "d:\\data\\backup.dat" /** @}*/// 文件名常量 /* * @name 系统状态常量 * @{ */ /** 正常状态 */ #define SYS_NORMAL 0 /** 故障状态 */ #define SYS_FAULT 1 /** 警告状态 */ #define SYS_WARNNING 2 /** @}*/// 系统状态常量 /** 枚举常量 */ typedef enum TDayOfWeek { SUN = 0, /**< 星期天 */ MON = 1, /**< 星期一 */ TUE = 2, /**< 星期二 */ WED = 3, /**< 星期三 */ THU = 4, /**< 星期四 */ FRI = 5, /**< 星期五 */ SAT = 6 /**< 星期六 */ } /** 定义类型 TEnumDayOfWeek */ TEnumDayOfWeek; /** 定义类型 PEnumDayOfWeek */ typedef TEnumDayOfWeek* PEnumDayOfWeek; /** 定义枚举变量 enum1 */ TEnumDayOfWeek enum1; /** 定义枚举指针变量 enum2 */ PEnumDayOfWeek p_enum2; /* * @defgroup FileUtils 文件操作函数 * @{ */ /* * 打开文件 \n * 文件打开成功后，必须使用 ::CloseFile 函数关闭。 * @param[in] file_name 文件名字符串 * @param[in] file_mode 文件打开模式字符串，可以由以下几个模块组合而成： * - r 读取 * - w 可写 * - a 添加 * - t 文本模式(不能与 b 联用) * - b 二进制模式(不能与 t 联用) * @return 返回文件编号 * - -1 表示打开文件失败 * @note 文件打开成功后，必须使用 ::CloseFile 函数关闭 * @par 示例: * @code // 用文本只读方式打开文件 int f = OpenFile("d:\\test.txt", "rt"); * @endcode * @see ::ReadFile ::WriteFile ::CloseFile * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。 */ int OpenFile(const char* file_name, const char* file_mode); /* * 读取文件 * @param[in] file 文件编号，参见：::OpenFile * @param[out] buffer 用于存放读取的文件内容 * @param[in] len 需要读取的文件长度 * @return 返回读取文件的长度 * - -1 表示读取文件失败 * @pre \e file 变量必须使用 ::OpenFile 返回值 * @pre \e buffer 不能为 NULL * @see ::OpenFile ::WriteFile ::CloseFile */ int ReadFile(int file, char* buffer, int len); /* * 写入文件 * @param[in] file 文件编号，参见：::OpenFile * @param[in] buffer 用于存放将要写入的文件内容 * @param[in] len 需要写入的文件长度 * @return 返回写入的长度 * - -1 表示写入文件失败 * @pre \e file 变量必须使用 ::OpenFile 返回值 * @see ::OpenFile ::ReadFile ::CloseFile */ int WriteFile(int file, const char* buffer, int len); /* * 关闭文件 * @param file 文件编号，参见：::OpenFile * @retval 0 为成功 * @retval -1 表示失败 * @see ::OpenFile ::WriteFile ::ReadFile * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。 */ int CloseFile(int file); /** @}*/// 文件操作函数 /** @}*/// 自动注释文档范例 生成的chm文档截图： 详情请见：https://www.wendangku.net/doc/d117860040.html,/ly4cn/archive/2005/11/23/282637.aspx https://www.wendangku.net/doc/d117860040.html,/seest/blog/item/efb5264cd21a4dfad72afc02.html 简介Doxygen 简介Doxygen (11) 什么是Doxygen? (11) 安装Doxygen (12) 设定Project的doxygen组态 (13) 撰写正确格式的批注 (16) 制作说明文件 (21) 什么是Doxygen? Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。 一个好的程序设计师，在写程序时，都会在适当的地方加上合适的批注。如果，能够在撰写批注时，稍微符合某种格式，接着就可以透过一个工具程序依据程序结构及您的批注产生出漂亮的檔。这将令许多工作繁重的程序设计师有时间多喝几杯咖啡。 Doxygen 就是这样的一个工具。在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的檔了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生檔。 目前Doxygen可处理的程序语言包含： ?C/C++ ?Java ?IDL (Corba, Microsoft及KDE-DCOP类型) 而可产生出来的檔格式有： ?HTML ?XML ?LaTeX ?RTF ?Unix Man Page 而其中还可衍生出不少其它格式。如有了LaTeX 档后，就可以透过一些工具产生出PS或是PDF档案。 在多国语言的支持方面，Doxygen 目前可支持的约有2,30种。自Doxygen 1.2.16开始支持繁体中文(这正是小弟做的好事)。所以在目前一些Open Source 的程序文件产生器中，Doxygen 算是相当完整的一套。在程序语言处理上面，Doxygen 也算是少数在Borland C++ Builder 的语法下还能够正常运作的工具之一（若非如此，小弟也不会推荐它）。 本文的目的是希望在经过仔细阅读本文之后能够给大家一个概略性的了解。以便可以很容易的上手使用Doxygen。至于Doxygen本身的详细使用，各位可以参考随着Doxygen 所附的檔。实际上，Doxygen 自己的使用手册就是使用Doxygen 产生的。您可以看到他实际上能够产生远比Reference Book更复杂的文件。 安装Doxygen Doxygen 的安装可说十分的简单，本文仅介绍binary档案的安装，若您有兴趣从source code重新compile起来，请自行查阅参考手册。 首先，请您先至doxygen 的网站上面抓取最新版本的doxygen 回来。目前，只要您是Linux, Solaris, Mac OS X, HP-UX, 甚至是UnixWare，都有compile 好的binary版本可以抓取。如果是Windows 95/98/ME/NT/2000/XP，甚至还有Setup的版本可以抓取。所以安装过程可说十分简单。只要给予正确的安装目录，相信一般在安装上是不会遇到什么问题的。 另外，如果您是Linux或是Windows，可以另外抓取Doxygen Wizard的程序。这是一个辅助工具，可以很快的帮您建立一个Doxygen 的组态档案。透过这个组态档案，您就可以很快的将檔产生出来。另外，若没有使用Doxygen Wizard，还是可以使用一般的文字编辑器将这个组态檔制作出来。 若安装成功，您应该可以看到doxygen 这个执行文件出现在您的系统中。若是Windows 平台，则可看到在程序集中有Doxygen 这个Folder出现。 设定Project的doxygen组态 Doxygen 产生檔可以分为三个步骤。一是为Project 建立组态檔，二是在程序代码中加上符合Doxygen所定义批注格式。三是使用Doxygen来产生批注。 因此，第一步就是为您的Project 制作Doxygen 的组态档案。这个所谓的组态档案，格式其实与很简单。就是一些Key 与值的设定。每个设定为一行。若第一行开头为"#" 表示该行为批注。Doxygen 会忽略它。每个设定行的格式有两种，分别如下： TAG = value [value, ...] 及 TAG += value [value, ...] 第一种形式是最常见的，也就是要设定一个TAG (也就是一个Key )，他的值为右边所定义的部分。原则上每个值都是单一的英文字，如果您要定义的值有空格符包含在内，可使用双引号将它括住。如果要定义的值超过一个以上，可使用逗号","予以分隔开来。 如果您要定义的TAG 是属于表列型态的，也就是他会有很多的值分别以逗号隔开。在Doxygen 组态檔中允许您在不同的地方重复定义。只是后面的定义应使用上面所说的第二种形式。此种形式会将前后两个定义的值合并在一起。 知道这个基本格式后，剩下就是根据各个TAG 的意义来进行设定。关于TAG 的定义很多，此处我们仅针对必要用到的TAG 进行说明，剩下的部分请自行翻阅使用说明。 由于Doxygen 的TAG 还算不少，为了方便使用，Doxygen 自身提供了一个方便的选项，可以帮您建立一份空白的Doxygen档案(Doxygen 是Doxygen 预设的组态檔名)。 > doxygen Doxygen 透过这个命令，您可以得到一个Doxygen 档案，接下来就可使用一般的文字编辑器来进行编辑。 下面将针对几个必要的TAG 进行说明： 若上面这些基本的Tag 都设定正确，接下来就是将您的Source Code 批注修改成为正确的格式。若您觉得用一般文字编辑器来编辑组态檔 很麻烦，建议您可以使用Doxygen Wizard这个工具程序。他可以很快的建构出您所需要的Doxygen档案。 撰写正确格式的批注 并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的格式撰写。原则上，Doxygen 仅处理与程序结构相关的批注，如Function，Class ，档案的批注等。对于Function内部的批注则不做处理。Doxygen可处理下面几种类型的批注。 JavaDoc类型： /** * ... 批注 ... */ Qt类型： /*! * ... 批注 ... */ 单行型式的批注： /// ... 批注 ... 或 //! ... 批注 ... 要使用哪种型态完全看自己的喜好。以笔者自己来说，大范围的注 解我会使用JavaDoc 型的。单行的批注则使用"///" 的类型。 此外，由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说，任何一个批注都是在说明其后的程序代码。如果要批注前面的程 式码则需用下面格式的批注符号。 /*!< ... 批注 ... */ /**< ... 批注 ... */ //!< ... 批注 ... ///< ... 批注 ... 上面这个方式并不适用于任何地方，只能用在class 的member或是function的参数上。 举例来说，若我们有下面这样的class。 class MyClass { public: int member1 ; int member2: void member_function(); }; 加上批注后，就变成这样： /** * 我的自订类别说明 ... */ class MyClass { public: int member1 ; ///< 第一个member说明 ... int member2: ///< 第二个member说明 ... int member_function(int a, int b); }; /** * 自订类别的member_funtion说明 ... * * @param a 参数a的说明 * @param b 参数b的说明 * * @return 传回a+b。 */ int MyClass::member_function( int a, int b ) { return a+b ; } 当您使用Doxygen 产生说明檔时，Doxygen 会帮您parsing 您的程 式码。并且依据程序结构建立对应的文件。然后再将您的批注，依据其位置套入于正确的地方。您可能已经注意到，除了一般文字说明外，还有一些其它特别的指令，像是@param及@return 等。这正是Doxygen 另外一个重要的部分，因为一个类别或是函式其实都有固定几个要说明的部分。为了让Doxygen 能够判断，所有我们就必需使用这些指令，来告诉Doxygen 后面的批注是在说明什么东西。Doxygen 在处理时，就会帮您把这些部分做特别的处理或是排版。甚至是制作 参考连结。 首先，我们先说明在Doxygen 中对于类别或是函数批注的一个特定格式。 /** * class或function的简易说明... * * class或function的详细说明... * ... */ 上面这个例子要说的是，在Doxygen 处理一个class 或是function注解时，会先判断第一行为简易说明。这个简易说明将一直到空一行的出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。两者的差异在于Doxygen 在某些地方只会显示简易说明，而不显示详细说明。如：class 或function的列表。 另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉Doxygen，何者是简易说明。例如： /** * @brief class或function的简易说明... * * class或function的详细说明... * ... */ 除了这个class 及function外，Doxygen 也可针对档案做说明，条件是该批注需置于档案的前面。主要也是利用一些指令，通常这部分注解都会放在档案的开始地方。如： /*! \file myfile.h \brief 档案简易说明 详细说明. \author 作者信息 */ 如您所见，档案批注约略格式如上，请别被"\" 所搞混。其实，"\" 与"@" 都是一样的，都是告诉Doxygen 后面是一个指令。两种在Doxygen 都可使用。笔者自己比较偏好使用"@"。 接着我们来针对一些常用的指令做说明： Doxygen 所支持的指令很多，有些甚至是关于输出排版的控制。您可从Doxygen 的使用说明中找到详尽的说明。 下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式： example.h: /** * @file 本范例的include档案。 * * 这个档案只定义example这个class。 * * @author garylee@localhost */ #define EXAMPLE_OK 0 ///< 定义EXAMPLE_OK的宏为0。 /** * @brief Example class的简易说明 * * 本范例说明Example class。 * 这是一个极为简单的范例。 * class Example { private: int var1 ; ///< 这是一个private的变数 public: int var2 ; ///< 这是一个public的变数成员。 int var3 ; ///< 这是另一个public的变数成员。 void ExFunc1(void); int ExFunc2(int a, char b); char *ExFunc3(char *c) ; }; example.cpp: /** * @file 本范例的程序代码档案。 * * 这个档案用来定义example这个class的 * member function。 * * @author garylee@localhost */ /** * @brief ExFunc1的简易说明 * * ExFunc1没有任何参数及传回值。 */ void Example::ExFunc1(void) { // empty funcion. } /** * @brief ExFunc2的简易说明 * * ExFunc3()传回两个参数相加的值。 * * @param a 用来相加的参数。 * @param b 用来相加的参数。 * @return 传回两个参数相加的结果。 */ int ExFunc2(int a, char b) 程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ COPYRIGHT (C), MicTiVo International. Co., Ltd. FileName: Author: C语言注释规范 1.注释原则 同一软件项目开发中，尽量保持代码注释规范和统一。 注释方便了代码的阅读和维护。 边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。 注释要简洁明确，不要出现形容词。 对于写的好的注释，我们将是第一个受益者。 大型软件开发中，通过别人的注释可以快速知道他人所写函数的功能，返回值，参数的使用。 2.文件头部的注释 示例： / * Program Assignment : 该文件的作用 * Author: 作者 * Date: 2013/8/6 14:34 * Description: 该文件的描述 *****/ /* * Source code in : 源代码的路径 * Function List: * initLinear 初始化线性表 * destoryLinear 释放线性表申请的空间 * isLinearEmpty 判断线性表是否为空 * isLinearFull 判断线性表是否为满 * getLinearElementValue 取得下标为index的元素的值 */ 注意：这个函数列表可以快速查询到我们想要了解的函数。 3.结构体，全局变量等的注释 示例： typedef POLYNOMIAL USER_TYPE; /* 新的数据类型的描述*/ int a; /* 全局变量的作用*/ /* 说明结构体的功能*/ typedef struct LINEAR { USER_TYPE *data; /* 每个成员的意义(作用) */ int maxRoom; /* 每个成员的意义(作用) */ int elementCount; /* 每个成员的意义(作用) */ }LINEAR; 4.函数的注释 在逻辑性较强的的地方加入注释，以便其他人的理解，在一定的程度上排除bug。 示例： /* * Function Name: getLinearElementIndex * Purpose: 取得元素的index值 * Params : * @LINEAR linear 线性表实例 * @USER_TYPE var 类型为USER_TYPE的实例 * @int (*)() cmp 提供接口，让用户定义具体比较函数 * Return: int 返回元素的index值 * Limitation: 如果返回-1，则代表不存在var的元素 */ int getLinearElementIndex(LINEAR linear, USER_TYPE var, int (*cmp)()) { /* * 如果逻辑太过复杂，这里写明该算法的过程和思路。 */ boolean found = FALSE; int i; for(i = 0; i < && !found; i++) if(cmp[i], var) == 0) found = TRUE; if(i >= i = NOT_FOUND; return i; } 1 Java 编程规范 1.1 排版 1.1.1 规则 规则1程序块要采用缩进风格编写，缩进的空格数为4个，不允许使用TAB缩进。(1.42+) 说明：缩进使程序更易阅读，使用空格缩进可以适应不同操作系统与不同开发工具。 规则2分界符（如大括号…{?和…}?）应各独占一行，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序 或者static、,synchronized等语句块中都要采用如上的缩进方式。(1.42+) 示例: if (a>b) { doStart(); } 规则3较长的语句、表达式或参数（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐， 语句可读。(1.42+) 示例： if (logger.isDebugEnabled()) { logger.debug("Session destroyed,call-id" + event.getSession().getCallId()); } 规则4不允许把多个短语句写在一行中，即一行只写一条语句(1.42+) 说明：阅读代码更加清晰 示例：如下例子不符合规范。 Object o = new Object(); Object b = null; 规则5if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while,switch等语句的执行语句无论多少都要加括号{},case 的执行语句中如果定义变量必须加括号{}。 (1.42+) 说明：阅读代码更加清晰，减少错误产生 示例： if (a>b) { doStart(); } 程序编写规范及约定 (仅供内部使用) 文档作者：_______________ 日期：___/___/___ 开发/测试经理：_______________ 日期：___/___/___ 项目经理：_______________ 日期：___/___/___ 请在这里输入公司名称 版权所有不得复制 目录 程序编写规范及约定 (3) 1编写目的 (3) 2代码编写风格 (3) 2.1单元风格 (3) 2.2语句风格 (3) 3命名规则 (3) 3.1命名约定 (3) 3.1.1标志符 (3) 3.1.2类class (3) 3.1.3枚举类型enum (4) 3.1.4委托delegate (4) 3.1.5常量const (4) 3.1.6接口interface (4) 3.1.7方法function (4) 3.1.8命名空间namespace (4) 3.1.9参数 (4) 3.1.10局部变量 (5) 3.1.11数据成员 (5) 3.1.12自定义异常类 (5) 3.1.13命名缩写 (5) 3.1.14数据库命名 (5) 3.2代码编写命名规范 (6) 3.3界面常用控件命名约定 (6) 3.4文件命名规范 (7) 3.4.1文档文件命名 (7) 3.4.2配置文件命名 (7) 3.4.3程序文件命名 (7) 程序编写规范及约定 1编写目的 为了使编写代码具有可读性、可理解性、可维护性，对程序编写人员代码实行统一风格，使得程序代码能够以名称反映含义、以形式反映结构。此文档可供程序代码编写人员及代码维护人员使用。 2代码编写风格 2.1单元风格 2.2语句风格 3命名规则 3.1命名约定 Pascal和Camel命名约定： 编程的命名方式主要有Pascal和Camel两种（Pascal：每个单词的首字母大写，例如ProductType；Camel：首个单词的首字母小写，其余单词的首字母大写，例如productType） 3.1.1标志符 规则：Pascal、Camel 实例与描述：例子说明 3.1.2类class 规则：Pascal 实例与描述：Application 百度文库- 让每个人平等地提升自我 1 程序代码注释编写规范 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* (C), MicTiVo International. Co., Ltd. 1.File : . History: Date: Author: Modification: 2. .. *************************************************/ 一、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ (C), MicTiVo International. Co., Ltd. FileName: Author: Version : Date: : / /*receive _process() */ 意:与溢出中断写初值不同} 程序代码注释编写规范 XXX份公司 为提高控制程序的阅读性与可理解性，现制定相关代码程序代码注释编写的编写规范。 一般情况下，源程序有效注释量必须在20％以上，注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。 常规注释有以下两种方式。 单行:以"//"符号开始，任何位于该符号之后的本行文字都视为注释。 多行:以"/*"符号开始，以"*/"结束。任何介于这对符号之间的文字都视为注释。 一、说明性文件 说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明。 示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************* COPYRIGHT (C), MicTiVo International. Co., Ltd. File NAME: // 文件 Author: Version: Date: // 作者、版本及完成日期 DESCRIPTION: // 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1.... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification: 2. .. *************************************************/ 二、源文件头 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。 示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。 /************************************************************ 1、头文件包含Includes 2、私有类型定义 Private typedef 3、私有定义Private define 4、私有宏定义 Private macro 5、私有变量 Private variables 6、私有函数原型Private function prototypes 7、私有函数Private functions 8、私有函数前注释 /****************************************************************************** * * Function Name : FSMC_NOR_Init * Description : Configures the FSMC and GPIOs to interface with the NOR memory. * This function must be called before any write/read operation * on the NOR. * Input : None * Output : None * Return : None ******************************************************************************* / 9、程序块采用缩进风格编写，缩进空格为4。 10、相对独立的程序块之间、变量说明之后必须加空行； 11、较长的字符（>80字符）要分成多行书写，长表达式要在低优先级操作符划分新行，操作符放在新行之首，新行要恰当缩进，保持排版整齐； 12、循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首; 13、若函数或过程中的参数较长，则要进行适当的划分。 14、不允许把多个短语句写在一行中，即一行只写一条语句。 15、if、for、do、while、case、switch、default等语句自占一行，且if、for、 do、while等语句的执行语句部分无论多少都要加括号{}。 16、对齐只使用空格键，不使用TAB键； 17、 函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case 语句下的情况处理语句也要遵从语句缩进要求 18、 程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一 列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以 及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。 19、 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或 目录 一．规范简介 1.1 目的 所有的程序开发手册都包含了各种规则。一些习惯自由程序人员可能对这些规则很不适应，但是在多个开发人员共同写作的情况下，这些规则是必需的。这不仅仅是为了开发效率来考虑，而且也是为了后期维护考虑。 本规范正是为培养规范设计和编程，养成良好的习惯，增强软件产品的稳定，健壮，可靠性；同时也为了提高软件的可读性，可以让程序员尽快而彻底地理解新的代码，使产品可维护性提高而制定的规范。 1.2 开发规范的重要性 （1）减少维护成本； 一个软件的生命周期中，80%的花费在于维护，另一方面，几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护，规范的编码减少人员变动带来的维护成本。 （2）改善软件的可读性 可以让程序员尽快而彻底地理解新的代码。在一个团队中，代码也容易在程序员之间共享。 （3）维护部门交付产品的规范形象。 二．具体规范 2.1 注释 注释是软件可读性的具体表现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。程序注释不能用抽象的语言，要精确表达出程序的处理说明。避免每行程序都使用注释，可以在一段程序的前面加一段注释，具有明确的处理逻辑。 注释必不可少，但也不应过多，不要被动得为写注释而写注释。 2.1.1 需要注释的部分 （1）文件头注释，文件创建及修改记录，版权归属，作者以及修订者，以及对文件的简短描述。 （2）类的目的（即类所完成的功能）、设置接口的目的以及应如何被使用。 （3）成员方法注释（对于设置与获取成员方法，在成员变量已有说明的情况下，可以不加注释；普通成员方法要求说明完成功能，参数含义以及返回值）。 （4）普通成员方法内部注释（控制结构、代码所起到的作用以及如此编写代码的原因，处理顺序等）。 （4）参数的含义以及其他任何约束或前提条件、字段或属性描述。而对于局部变量，如无特别意义的情况下则不加注释。 2.1.2 具体注释 （1）文件头注释 要求：遵循JavaDoc的规范，在每一个源文件的开头注明该文件的作用, 作简要说明, 并写上源文件的作者,版权信息编写日期。如果是修改别人编写的源文件，要在修改信息上注明修改者和修改日期。 例子： /** * @Title: 文件名 * @Copyright (C) 年份龙图软件 * @Description: 文件信息描述 * @Revision History: * @Revision 版本号日期作者. */ （2）类和接口的注释 要求：遵循JavaDoc的规范，在每一个类的开头注明该类的作用，作简要说明，并写上作者，编写日期。 例子： /** * @ClassName: 类（或接口）名 * @Description: Description of this class 程序注释规范说明 程序注释规范应包括以下三方面： 一、文件头部注释 在代码文件的头部进行注释，这样做的好处在于，我们能对代码文件做变更跟踪。在代码头部分标注出创始人、创始时间、修改人、修改时间、代码的功能，这在团队开发中必不可少，它们可以使后来维护/修改的同伴在遇到问题时，在第一时间知道他应该向谁去寻求帮助，并且知道这个文件经历了多少次迭代、经历了多少个程序员的开发和修改。 样本： /***************************************************** ** 作者：Liuchao ** 创始时间：2007-11-12 ** 修改人：Liuchao ** 修改时间：2007-11-12 ** 修改人：Liaochao ** 修改时间：2007-11-12 ** 描述： ** 主要用于产品信息的资料录入，… *****************************************************/ 二、函数、属性、类等注释 请使用///三斜线注释，这种注释是基于XML的，不仅能导出XML制作帮助文档，而且在各个函数、属性、类等的使用中，编辑环境会自动带出注释，方便你的开发。以protected，protected Internal，public声明的定义注释都建议以这样命名方法。 例如： /// /// 用于从ERP系统中捞出产品信息的类 /// class ProductTypeCollector { … } 三、逻辑点注释 在我们认为逻辑性较强的地方加入注释，说明这段程序的逻辑是怎样的，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG。在注释中写明我们的逻辑思想，对照程序，判断程序是否符合我们的初衷，如果不是，则我们应该仔细思考耀修改的是注释还是程序了… 四、变量注释 我们在认为重要的变量后加以注释，说明变量的含义，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG.我们常用///三斜线注释。 /// 用于从ERP系统中捞出产品信息的类 class ProductTypeCollector { int STData;/// 在软件开发的过程中总是强调注释的规范，但是没有一个具体的标准进行说明，通常都是在代码编写规范中简单的描述几句，不能作为一个代码注释检查的标准和依据，做什么都要有一个依据吗:),现在我特整理了一个《Java的注释规范》，内容来自网络、书籍和自己的实际积累。 JA V A注释规范 版本/状态作者版本日期 1.0 ghc 2008-07-02 一、背景 1、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分析这段代码，我们需要什么样的注释信息？ 2、怎么样避免我们的注释冗长而且凌乱不堪呢？ 3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？ 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本, 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力。 三、注释的原则 1、注释形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。 2、注释的简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 3、注释的一致性 在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。 4、注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。 5、注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。 6、删除无用注释 Java编程规范 本编程规范建立在标准的Java编程规范的基础上，如和标准的Java编程规范有冲突，以本编程规范为准。 1.1 程序结构 包名 引入包/类名 类注释 类 常量//常量注释 构造器注释 构造器 构造器注释 构造器 方法注释 方法 方法注释 方法 1.2 命名规范 命名规范使得程序更易理解，可读性更强。并且能够提供函数和标识符的信息。 文件命名规范： java程序使用如下的文件名后缀： 文件类型后缀 Java 源文件.java Java 字节码文件.class 对系统的文件命名方式有待于根据实际业务决定。 包命名规范： 包名应该唯一，它的前缀可以为任何小写的ASCII字符，包名按照公司内部的命名规范，这些规范指出了某种目录名，主要包括部门，项目，机器，或者登录名。 命名规则为： app.系统名.模块名.xxx.xxx 包命名举例： app.oa.interceptor.xxx app.oa.sys.xxx 类命名规范： 类名应该是名词，并且是大小写混合的。首字母要大写。尽量保证类名简单并且描述性强。避免使用只取单词首字母的简写或者单词的缩写形式，除非缩写形式比单词的完整形式更常用（例如：URL或者HTML）。文件名必须和public的类名保持一致，注意大小写（JBuilder 等一些编译器可以忽略大小写，要特别注意）。如是实现类命名后缀+Impl。 类命名举例： classLoginAction; classUserServiceImpl; 接口命名规范： 接口命名方式与类命名方式相同。 接口命名举例： interfaceIUserService; interfaceSysYhjsDAO; 方法命名规范； 方法名应该为动词，并且是大小写混合的。首字母要小写，方法名的第 二个单词的第一个字母大写。 方法命名举例： String getNoticeNo(); Collection findByCondition(String); 变量命名规范 变量，以及所有的类实例应为首字母小写的大小写混合形式。变量名的第二个单词 的首字母大写。变量名的首字母不能为下划线或者$符。 变量名应该尽可能的短小，但要有意义。变量名应该便于记忆，也就是说变量名应 该尽可能的做到见名知意。除了暂时使用的变量外（一般用于循环变量），应该避免使 用只有一个字母的变量名。对于临时变量一般说来：i，j，k，m，n代表整型变量。c，d，e代表字符型变量。 变量命名举例： String dataType; String name; inti; char c; 常量命名规范： 声明为类常量的变量或者ANSI常量应该全部为大写字母，并且每个单词间用下划 线“_”隔开。为了便于调试，应避免使用ANSI常量。 常量命名举例： static final int MIN_WIDTH = 4; 1.3 注释规范 Java 提供了两种类型的注释：程序注释和文档注释。程序注释是由分隔符/*…*/，和// 隔开的部分，这些注释和C++ 中的注释一样。文档注释（即“doc 注释”）是Java 独有的。由分隔符/**…*/隔开。使用javadoc工具能够将文档注释抽取出来形成HTML 文件。程序注释主要是对程序的某部分具体实现方式的注释。文档注释是对程序的描述性注释，主要是提供给不需要了解程序具体实现的开发者使用。注释应该是代码的概括性描述，提供不易直接从代码中得到的信息，并且只包含对阅读和理解程序有用的信息。例如注释中包含相应的包如何编译或者在哪个目录下，而不应该包括这个包驻留在哪儿的信息。注释中可以描述一些精妙的算法和一些不易理解的设计思想，但应该避免那些在程序代码中很清楚的表达出来的信息。尽可能的避免过时的信息。错误的注释比没有注释更有害。经常性的注释有时也反映出代码质量的低下。 …程序注释： 程序注释有四种格式：块注释格式，单行注释，跟随注释，行尾注释 ?块注释格式 块注释主要用于描述：文件、方法、数据结构和算法。一般在文件或者方法定义的 之前使用。也可以用在方法定义里面，如果块注释放在函数或者方法定义里，它必须与它所描述的代码具有相同的缩进形式。 代码编写规范说明书（c#.net与https://www.wendangku.net/doc/d117860040.html,）目录 1 目的 2 范围 3 注释规范 3.1 概述 3.2 自建代码文件注释 3.3 模块（类）注释 3.4 类属性注释 3.5 方法注释 3.6 代码间注释 4 命名总体规则 5 命名规范 5.1 变量（Variable）命名 5.2 常量命名 5.3 类（Class）命名 5.4 接口（Interface）命名 5.5 方法（Method）命名 5.6 名称空间Namespace）命名 6 编码规则 6.1 错误检查规则 6.2 大括号规则 6.3 缩进规则 6.4 小括号规则 6.5 If Then Else规则 6.6 比较规则 6.7 Case规则 6.8 对齐规则 6.9 单语句规则 6.10 单一功能规则 6.11 简单功能规则 6.12 明确条件规则 6.13 选用FALSE规则 6.14 独立赋值规则 6.15 定义常量规则 6.16 模块化规则 6.17 交流规则 7 编程准则 7.1 变量使用 7.2 数据库操作 7.3 对象使用 7.4 模块设计原则 7.5 结构化要求 7.6 函数返回值原则 8 代码包规范 8.1 代码包的版本号 8.2 代码包的标识 9 代码的控制 9.1 代码库/目录的建立 9.2 代码归档 10 输入控制校验规则 10.1 登陆控制 10.2 数据录入控制 附件1：数据类型缩写表 附件2：服务器控件名缩写表 1 目的 一.为了统一公司软件开发设计过程的编程规范 二.使网站开发人员能很方便的理解每个目录,变量，控件，类，方法的意义 三.为了保证编写出的程序都符合相同的规范，保证一致性、统一性而建立的程序编码规范。 四.编码规范和约定必须能明显改善代码可读性，并有助于代码管理、分类范围适用于企业所有基于.NET平台的软件开发工作 2 范围 本规范适用于开发组全体人员，作用于软件项目开发的代码编写阶段和后期维护阶段。 3 注释规范 3.1 概述 a) 注释要求英文及英文的标点符号。 b) 注释中，应标明对象的完整的名称及其用途，但应避免对代码过于详细的描述。 c) 每行注释的最大长度为100个字符。 d) 将注释与注释分隔符用一个空格分开。 e) 不允许给注释加外框。 f) 编码的同时书写注释。 g) 重要变量必须有注释。 h) 变量注释和变量在同一行，所有注释必须对齐，与变量分开至少四个“空格”键。 如：int m_iLevel,m_iCount; // m_iLevel ....tree level // m_iCount ....count of tree items string m_strSql; //SQL i) 典型算法必须有注释。 j) 在循环和逻辑分支地方的上行必须就近书写注释。 k) 程序段或语句的注释在程序段或语句的上一行 l) 在代码交付之前，必须删掉临时的或无关的注释。 m) 为便于阅读代码，每行代码的长度应少于100个字符。 3.2 自建代码文件注释 对于自己创建的代码文件（如函数、脚本），在文件开头，一般编写如下注释： /****************************************************** FileName: Copyright (c) 2004-xxxx *********公司技术开发部 Writer: create Date: Rewriter: FORTRAN 90 程序编程规范 Fortran 90 编程规范，使程序代码高度组织化，更加易读、易懂、易于维护，程序更加高效。使编出的程序更易懂、易于维护。 1 语言选择 数值预报创新系统软件开发应避免使用Fortran77 的某些过时特征以Fortran 90不一致的特征。选择Fortran 90 作为开发语言，并采用Fortran 90 的新功能，如动态内存的分配(dynamic memory allocation)、递归（recursion ）, 模块(modules)、POINTER 、长变量名、自由格式等。 Fortran 77其中某些只是一些冗余的功能，这些功能已经过时，另外，还有一些在Fortran90 中被证明是不好的用法，建议不要使用。 2 Fortran 90 的新特性 2.1.1 建议使用的Fortran 90 新特性 建议使用Fortran 90 提供的模块（module ），并用Use ONLY 指定module 中哪些变量或派生类型定义可用于调用程序。 尽量使用数组下标三元组，这样可优化并减少所需的代码行数。为提高可读性，要在括号内表明数组的维数，例如： 1dArrayA(:) = 1dArrayB(:) + 1dArrayC(:) 2dArray(: , :) = scalar * Another2dArray(: , :) 当访问数组的子集时，例如在有限差分等式中，可以通过使用下标三元组实现。例如：2dArray(: , 2:len2) = scalar *（ & Another2dArray(:, 1:len2 -1) & - Another2dArray(:, 2:len2) & ) 对程序单元（program units ）命名，并使用End program ，End subroutine ，End interface ，End module 等结构再次指定“program unit ”的名称。 在逻辑表达式中使用>、 >=、 ==、 <、 <=、 /=，它们分别代 替.gt.、.ge.、.eq.、.lt.、.le.、.ne. 。新的表示方法更接近标准的数学符号 在变量定义中始终使用“：：”；始终用“DIMENSION ”定义数组形状；始终用（len=）的语法格式声明字符变量的长度。 Comments criterion of the Code 在多个PROJIECT共同开发的前提下，为了减少修改升级CODE过程中出现失误和方便SI 人员对代码的维护，加强部门整体代码注释规范，建议通过在每一次代码修改过程中添加代码标志符进行注释，这样可以使软件工程师在升级代码的过程中减少错误率，同时可以保持对以前版本代码的修改思路清晰，能在最短时间里复查代码中的错误。 标准C++/C的文件结构： // Copyright (c) Microsoft Corporation. All rights reserved. // Use of this source code is subject to the terms of the Microsoft end-user // license agreement (EULA) under which you licensed this SOFTWARE PRODUCT. // If you did not accept the terms of the EULA, you are not authorized to use // this source code. For a copy of the EULA, please see the LICENSE.RTF on your // install media. /** * Port Copyright (c) Hisys Corporation. All rights reserved. * @file batt_pdd.c * Abstract * This file contains battery driver PDD implementation. * Change Log * 2006.2.21 Shi Yuehua Initial Version * **/ 代码注释规范如下： //***********COMMENTS-HISTORY***********// /****************************************************************************** *NAME | SIGN | PROJECT | SUMMARY * *------------------------------------------------------------------------------ *Johson.Li M060806_A HXS006 Use the two methods to measure the battery voltage. *Johson.Li M060812_A HXS010 Change the init array value from 4 to 8. *Johson.Li M060812_B COMMON Change the USB CHANGING conditions. * ........... * ........... ******************************************************************************/ 代码注释标题声明包含四部分： 1.作者名称 2.标记符 3.项目名称 4.摘要 1.《NAME》：修改该部分CODE的软件人员名称（英文名称&中文名称拼音缩写），第一个字母大写。 2．《SIGN》：该标记符应在所有本次修改代码前面声明，主要是为了方便搜索，当我们想查找本次为了实现某个功能所做的代码修改时，可以搜索此标记符，即可找到全部修改过的相关代码段。 标记符：M060806_A M: 英文 C++注释规范 版本：1.0 制定部门：技术架构部C++基础架构组 2006.8 目录 1说明 (3) 2注释种类 (3) 2.1重复代码 (3) 2.2解释代码 (3) 2.3代码标记 (3) 2.4概述代码 (3) 2.5代码意图说明 (4) 2.6传达代码无法表达的信息 (4) 3注释原则 (4) 3.1站在读者的立场编写注释 (4) 3.2注释无法取代良好的编程风格 (4) 3.3好注释能在更高抽象层次上解释我们想干什么 (5) 4规范细则 (5) 4.1文件注释规范 (5) 4.2名字空间注释规范 (6) 4.3类定义注释规范 (7) 4.4数据声明注释规范 (8) 4.5函数注释规范 (8) 4.6代码标记注释规范 (10) 5FAQ (10) 5.1枚举值需要注释吗？ (10) 5.2前置条件、后置条件和不变式有必要注释出来吗？ (10) 5.3写注释太耗时间怎么办？ (11) 5.4有效的注释是指什么？ (11) 参考书目 (11) 参考工具 (11) 1说明 本文档用于规范C++代码中注释的编写。规范中提出的多数注释格式都来源于文档生成工具doxygen，所以遵从本规范进行注释的C++代码都可以使用doxygen生成美观一致的代码文档。 同时另一方面，美观绝非衡量文档质量的唯一标准。文档内容准确与否，是否充分，以及语言组织是否清晰流畅，这些都是决定一份文档质量的重要标准。遗憾的是，这些标准当中有不少需要通过主观加以判断，很难进行明确的规范。 所以我们将尽可能的提供明确的评判标准，同时，本规范中也不可避免的提出了一些比较主观的注释要求或是建议，这些要求或是建议多数都来自于众多先驱多年的开发经验。遵循它们不仅有助于生成一份美观的代码文档。更重要，依照这些要求和建议来编写注释，能够有效的帮助开发者在早期就反省自己设计的合理性，同时也为编写单元测试提供更多的帮助。 2注释种类 2.1重复代码 重复性注释只是用不同文字把代码的工作又描述一次。他除了给读者增加阅读量外，没有提供更多信息。 2.2解释代码 解释性注释通常用于解释复杂、敏感的代码块。在这些场合他们能派上用场，但通常正是因为代码含混不清，才体现出这类注释的价值。如果代码过于复杂而需要解释，最好是改进代码，而不是添加注释。使代码清晰后再使用概述性注释或者意图性注释。 2.3代码标记 标记性注释并非有意留在代码中，他提醒开发者某处的工作未做完。在实际工作中，我们经常会使用这些注释作为程序骨架的占位符，或是已知bug的标记。 2.4概述代码 概述性注释是这么做的：将若干代码行的意思以一两句话说出来。这种注释比重复性注释强多了，因为读者读注释能比读代码更快。概述性注释对于要修改你代码的其他人来说尤 JA V A编程规范试题 一、判断题（每题2分，共28分） 1、if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while, switch, case等语句的执行语句无论多少都要加括号{}。× 2、包的注释内容要求包括：简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权、生成日期等。× 3、类注释部分，描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者、新版本号和当天的日期，@since 表示从那个版本开始就有这个类或者接口，@deprecated 表示不建议使用该类或者接口。× 4、对于方法内部用throw语句抛出的异常，必须在方法的注释中标明；对于所调用的其他方法所抛出的异常，在注释中要求说明所有的异常；对于非RuntimeException，即throws 子句声明会抛出的异常，必须在方法的注释中标明。× 5、类名和接口使用完整的英文单词描述，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。× 6、com.huawei.四级部门名称.项目名称，符合包命名规范。√ 7、不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且异常的跳转流程难以预测。√ 8、划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的多样化。× 9、一个方法不应抛出太多类型的异常，如果程序中需要分类处理异常，则将异常根据分类组织成继承关系。√ 10、switch 语句中的case 关键字要和后面的常量保持一个空格；如果有特殊的需要要在switch语句中定义case以外的标签，需要在注释中说明。× 11、没有被覆盖的友好方法和没有子类的友好类应该定义成final。√ 12、简单的类可以通过名字比较两个对象的类，推荐使用getClass()或者instanceof()。× 13、不要调用Thread 类的resume(), suspend(),sleep(), stop() 方法。× 14、判断方法是否是重载，只关注方法名、参数个数、参数类型，不关注方法返回值；√ 二、单选题（每题2分，共36分） 1、下面的选项与公司的排版规范不相符的是B A．如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在Java语言中括号已是最清晰的标志了。 B． DatabaseKey servicekey = null; key = getServiceKey(); currentEventsCount = getCurrentEventsCount(); if (currentEventsCount > 0 ) { //...program code } C． if ( writeToFile ) { writeFileThread.interrupt(); }程序代码注释编写规范
C语言注释规范
华为JAVA编程规范
程序代码编写规范
程序代码注释编写规范
程序代码注释编写规范
C语言编写规范之注释
代码规范
程序源代码注释规范
java注释规范总结大全
java编程规范+数据库命名规范
代码编写规范说明书
FORTRAN 90 程序编程规范
代码注释规范说明
C 注释规范
JAVA编程规范试题