代码规范 - Geminiv/CgvWiki GitHub Wiki

代码规范

该文档定义了项目代码规范

1. 命名规范

总体风格采用帕斯卡命名法 Pascal Case / 大驼峰命名法 Camel Case。
可以使用简称，但简称一定要被熟识且没有歧义，简称包括 2 种：
- 专有简称，例 NURBS （NonUniform Rational B-Spline），命名根据专业简称习惯
- 缩略简称，例 control，缩略为 ctl，遵守命名规则为 Ctl 或局部变量 ctl，原则上类命名、函数命名不使用缩略。

1.1 变量命名规范

变量类型	规范	示例
成员变量	m_变量名	m_PointCount
形参变量（仅使用参数，一般加const修饰）	p_变量名	p_PointCount
实参变量（修改参数，一般使用引用）	r_变量名	r_PointCount
返回变量	r_变量名	r_PointCount
临时变量（局部变量）	小写开头，后面大写开头	pointCount

1.2 可用公认缩写

原单词	缩写单词	使用要求
Previous	Prv	不得单独使用，后应接具体的内容，例如 PrvPoint，后接单词不能再缩写
Next	Nxt	不得单独使用，后应接具体的内容，例如 NxtPoint，后接单词不能再缩写

2. 注释规范

该项目采用doxygen这一帮助文档生成工具，因此代码注释需符合其可识别的格式。

通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两种说明方式都是可选的。而方法和函数也可能使用第三种说明方式（in body），并包含方法和函数内所有注释块间的联系。

建议简要说明使用一个短小的单行方式，而详细说明要提供足够的长度以包含更多的细节描述。“in body”可看作详细说明，或者一系列说明的集合。

2.1 注释风格

2.1.1 详细说明样例

可使用JavaDoc风格，包含两个“*”开头的C注释风格，实例如下：
```
/**
 * ...text...
 */
```
也可使用Qt风格，即在C注释风格基础上添加一个“！”字符，实例如下：
```
/*!
 * ...text...
 */
```
中间的“*”号是可选的，下面的例子也是有效的：
```
/*!
 ...text...
 */
```
第三种替代方式为使用至少两行的C++注释块，在每行开始处处一个“/”或者“！”，例子如下：
```
///
/// ...text...
///
```
```
//!
//! ...text...
//!
```
此情况，请使用一条空行作为文档块的结尾。

注释块亦可采用以下此种注释块样式：

/********************************************//**
 *  ... text
 ***********************************************/

（注意前两条斜杠为结束普通注释块，而后两条为特殊注释块）

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

/************************************************
 *  ... text
 ***********************************************/

2.1.2 简要说明样例

在一个注释块之前使用\brief 命令。这个命令能在一个段落的末尾处终止它，并在一条空白行之后紧跟详细说明。例子如下：
```
/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */
```
如果在配置文件中将 JAVADOC_AUTOBRIEF设置为YES，可使用JavaDoc注释块，并直接开始一段简要说明，在出现第一个“.”处结束（此处只支持半角句点），后跟一个空格或反斜杠，亦或空白行，之后便可开始详细说明。例子如下：
```
/** Brief description which ends at this dot. Details follow
 *  here.
 */
```
此选项标记对于多行的C++注释块亦有效：
```
/// Brief description which ends at this dot. Details follow
/// here.
```
同样，若希望Qt文档块自动将第一条句子作为简要说明，需将QT_AUTOBRIEF设置为YES。

对于不超过一行的C++注释块可使用以下方式：

/// Brief description.
/** Detailed description. */

或者

//! Brief description.
//! Detailed description 
//! starts here.

2.2 后置注释

当为一个结构体，枚举或类添加注释时，有时也需要为他们的成员添加注释，且希望将注释放置于代码的后面，此时在注释块中加入“<” 标记即可。示例如下：

int var; /*!< Detailed description after the member */

int var; //!< Detailed description after the member
         //!<

2.3 结构化命令

结构化命令由一个反斜杠“/”或"@"开始，紧跟一个命令字和若干参数。结构化命令用于对文件本身，及其包含的类、函数、类型转换、枚举、结构体、宏等等结构进行注释。以下仅对常用的结构提供详细的样例与说明，其余结构结合特殊命令字表，参照样例添加注释。

2.3.1 文件注释

/**
 * @file myfile.h
 * @author name
 * @version 1.0
 * @date 2020-09-27
 * @brief this brief
 * @details this's details
 */

说明：

文件注释为doxygen进行文本识别的必须条目，不可省略，文件中至少有一行：
```
/*! \file */ 
```
或者
```
/** @file */ 
```
“@file”后的文件名需与当前文件名一致

2.3.2 结构体注释

简洁样式

struct ListNode         ///  the brief structcomment
{
    ListNode* m_next;   ///< The brief mement comment
    Node* m_node;       ///< The brief mement comment
};

详细样式

/**
 * this is details struct
 */
typedef struct DynamicConfigT   ///  The brief mementcomment
{
         int     nApplyId;      ///< The brief mement comment
         int     nTime;         ///< The brief mement comment
         int     nReboot;       ///< The brief mement comment

    /** this is details mement comment */
         char**  aValTable;     ///< The brief mement comment
         LocalHndl   pfnHndl;   ///< The brief mement comment
} DynamicConfig;

说明

“///”与注释间留有2个空格
“///<”与注释间留有1个空格
结构体成员的详细注释写在该成员上面
结构体成员的详细注释与上一成员间留1个空行
推荐结构体使用typedef类型定义
推荐使用简洁的结构体注释

2.3.3 宏注释

简洁样式

/// This macro is toolong, so comment here briefly!
#define HTTP_REQUEST_LEN_MAX    APPLY_BUF_SIZE_BIG

详细样式

/**
 * The detail macro comment, may be multi-line.
 * @param a The brief parameter comment
 * @param b The brief parameter comment
 * @return The brief return value comment
 */
#define MAX(a, b) ((a) > (b))? (a) : (b)

说明

2.3.4 函数注释

简洁样式

/// The brieffunction comment, may be multi-line.
static int apply_login();

详细样式

/**
 * The detail function comment, may be multi-line.
 * @param cur_id The brief parameter comment
 * @return The brief return value comment
 * @brief The brief function comment
 */
static int reboot_enable( intcur_id )

说明

详述进行函数简要说明时需添加“@brief”；
无参无返回值的函数使用简洁样式；