代码注释规范(2)

 

2    注释规范要求

下面以C++中的头文件为例来说明如何进行注释，以及注释要求。

注意：由于blog显示原因，把其中的pre1改为pre，把b1改为b，删掉[注释*]字样。

/*** @file example.h[注释1] * @brief 这是一个注释格式说明文件[注释2] * @author Wang Erxiao[注释3] * @author Si Maguang[注释4] * @date 2011-07-27 22:30:00[注释5] * @version 1.0[注释6] * <pre1><b1>Copyright (C) </b> 1998-2009 Comany Name </pre1>* <pre1><b1>email:</b> [e-mail]; [e-mail][注释7] </pre1>* <pre1><b1>company:</b>http://blog.csdn.net/donhao</pre1>* <pre1><b1>All rights reserved.</b1></pre1>* <pre1><b1>modification:</b1></pre1>* <pre1>Write modifications here.</pre1>[注释8] */#include <string>/** @brief枚举常量. */[注释9] typedef enum DayOfWeek{SUN = 0,     /**< 星期天 */[注释10] MON = 1,     /**< 星期一 */TUE = 2,     /**< 星期二 */WED = 3,     /**< 星期三 */THU = 4,     /**< 星期四 */FRI = 5,     /**< 星期五 */SAT = 6      /**< 星期六 */}/*** @class example* @brief 封装了日志操作。** detailed 基于网络的日志系统。*/[注释11]class example{public:/*** @brief Constructor for Example, 这里是简要描述，同时演示了\n* 简要描述换行。* 这里是详细描述，同时演示了\n* 详细描述换行。* @param configuationFilePath Defaults to "./ Example.conf". The path and* file name of the configuration file.*/Example(std::string configuationFilePath = "./ Example.conf");/** @brief Destructor for Example. */~Example();/*** @defgroup Send_messages 这是Send_messages模块的Title* @brief Send_messages模块的简要描述。** Send_messages模块的详细描述。* @{*/[注释13] /*** @brief 向系统发送一条Emergence级别的消息.** emerg函数的详细描述。* @param[in] message The content of the log message.* @return bool* @see log* @note 注释* @since 2008-10-10* @exception LogException* @deprecated*/[注释14]bool emerg(std::string message);/** @} */ //Send_messages模块定义结束，其中包括一个函数。 /*** @addtogroup Send_messages* @{[注释15]*/ /*** @brief Send a fatal log message to existing appenders.* @param[out] message The content of the log message.*/void fatal(std::string message);/*** @brief Send an alert log message to existing appenders.* @param[in] message The content of the log message.* @return void*/void alert(std::string message);/** @} */ //所要添加进的模块结束/*** @name gourp_name* @brief gourp_name组的简要注释。** gourp_name组的详细注释。* @{*//*** @brief Send a notice log message to existing appenders.* @param[in] message The content of the log message.* @return void*/void notice(std::string message);/** @} */ //组结束/*** @brief Send a log message with priority priorityLevel to existing appenders.* @param[in] priorityLevel The priority of the log message.* - LOG_EMERG       0* - LOG_FATAL        1* - LOG_ALERT       2* - LOG_NOTICE      3* - LOG_INFO         4[注释16]* @param[in] message The content of the log message. * @return void*/void log(int priorityLevel, std::string message); /*** @brief Get the message sending status.* @return bool*/bool getSendStatus();/*** @file test.h* @ingroup Send_messages* @brief 添加文件test.h到Send_messages模块。*/[注释17] /*** @namespace std* @ingroup Send_messages* @brief 添加命名空间std到Send_messages模块。*/[注释18] /*** @class test* @ingroup Send_messages* @brief 添加类test到Send_messages模块。*/[注释19] };

---

 [注释1]文件名

 [注释2]在这里写文件描述。

 [注释3]作者姓名。注意@author和姓名之间要保持一个空格。

 [注释4]如果为多个作者，则另起一行在@author之后写上作者姓名。

 [注释5]日期。

 [注释6]代码版本。

 [注释7]作者邮箱。

 [注释8]可以根据具体需求来修改以上内容。

 [注释9]简要注释的格式。

 [注释10]成员注释的格式

 [注释11]类注释的格式，其中包括类名（自动生成）、简要注释、详细注释。

    1.       简要描述一定以@brief开始（自动生成）。

    2.       简要注释之后空一行才是详细注释。

 [注释12]注释换行的方法。

 [注释13]定义模块注释的方法，其模块结束标识为/** @} */

 [注释14]函数注释

 [注释15]将从此处至“/** @} */ //组结束”之前的内容添加至Send_messages模块中。

 [注释16]项目符号标记。

 [注释17]文件test.h属于模块Send_messages。

 [注释18]命名空间std属于模块Send_messages。

 [注释19]类test属于模块Send_messages。