编码规范-注释管理

4.注释
除非极其简单，否则对关键信息应有注释说明。内容包括：功能、入口/出口参数，必要时还可有备注或
补充说明。
①　注释用途：代码交流、代码阅读、代码review、新人培训、工作移交等。
②　统一采用业界的文档标准：doxygen。
③　代码进行了修改，注释需要同步修改。
④　注释内容意思要与代码保持一致。

注释分为：块注释和行注释。
块注释：

/**
*@brief     块注释内容说明
*/

行注释：变量注释一般为行注释。

//注释内容说明。

4.1.类注释
对每个类进行简单的注释说明。内容包括：类名称含义、类主要用途、作者、创建日期。
样例：

/**
 * @class       设备窗口操作类
 * @brief       操作工通过该窗口进行设备查询、设备状态、设备配置等操作
 * @author      作者名称
 * @date        创建、修改日期
 */
class RTX_MOD CDialogDev : public QDialog, CRTDialog

4.2.函数注释
对每个函数/接口进行相应的注释说明。内容包括：函数含义、传入参数、传出参数、返回值、特殊说明（内存管理）等。
序号 关键字 关键字函数 说明
1. @brief 函数功能简要说明
2. @remark 特殊说明
3. @param[in] 传入参数
4. @param[out] 传出参数
5. @param[in|out] 传入/传出参数
6. @return 返回类型
7. @retval 返回值

①　有传入参数、有传出参数、有返回值必须需要函数注释。
②　代码行数小于10行的函数可以不需要函数注释。（不包括注释和空行）
③　代码行数大于10行的行数应该需要函数注释。（不包括注释和空行）
④　代码行数大于50行的函数必须进行函数注释。（不包括注释和空行）

样例：

    /**
    *@brief     通过规则id获取条码规则详情列表
    *@remark    条码规则的指针和内存共用
    *@param[in] 规则id
    *@retval    符合规则id的条码规则详情列表
    */
CEQue<CRTBarcodeRuleDetail*> GetDetail(int i32RuleID);

4.3.变量注释
对每个变量进行相应的注释说明。内容包括：变量名称含义、变量类型、变量长度、变量值范围、变量默认值等。
①　注释内容相对简单的，放在变量名称后面。
②　注释内容相对复杂的，放在变量名称上一行。

样例：

QString             m_strDevName;           //设备名称
//设备类型：1为1500型号，2为208型号，3为212型号，4为410型号，默认值为2
quint32             m_ui32DevType;   

4.4.关键业务注释
对系统/项目中的关键业务进行相关的注释说明。内容包括：业务规则说明、处理细节、特殊说明、修改人、修改时间等。

样例：

    //add by hls begin 20140723
    //修改实施部qc311：质检表单内有质检项目存在空值时限制提交
    //目的：减少车间管理难度，由人工检查质检数据有效性变为系统防错
    //现有流程：1、终端质检时点击增加，没有输入数据直接确定时系统把【】值写到每个质检项中，
//建议改善如下：1、终端质检时点击增加，没有输入数据直接确定时限制操作，同时弹窗提示；
//2、在刷卡提交质检表单时，判断是否有空值的质检项目，有空值时限制提交并弹窗提示；
    int irow = 0;
    int icol = 0;
    string strCellValue = "";
    for (irow = 0;irow < pGrid->RTGetRowCount();irow++)
    {
        //列名称：项目名称、记录、记录.....、记录n、判定、修正值
        //需要剔除开始的项目名称和结尾的判定与修正值
        //RTGetColCount()会多返回一行，所有默认列字段需要减（除了判定和修正值）
        for (icol=1; icol < pGrid->RTGetColCount()-3; icol++)
        {
            strCellValue = "";
            strCellValue = pGrid->RTGetValue(irow,icol);
            //有任一一个质检项目的记录值为空值都不能通过，需要弹窗提示
            if (strCellValue.empty())
            {
                string str = "";
                util::string_format(str, "第[%d]行第[%d]列的质检项目的记录值的内容不能为空值，请重新填写", irow+1, icol+1);
                PopMsg(str.c_str());
                return;
            }
        }
    }
//add by hls end 20140723

4.5.关键算法注释
对系统/项目中的关键算法进行相关的注释说明。内容包括：算法功能说明、算法公式说明、特殊说明、修改人、修改时间等。

4.6.内嵌代码的注释
对于if、while、do 等其大括号内嵌代码块比较长(需拖动滚动条来看)或者多层嵌套时，在结尾的“}”后要加上其所对应的语句的注释说明。
例：

if (bIsOk == TRUE)
{
代码段
}// if ((bIsOk == TRUE)...

4.7.缺省值的注释
函数入口参数有缺省值时，应注释说明。
例:

BOOL MyFunction(
const char cszParam1 [],
BOOL bParam2 // = TRUE
);

或者：

BOOL MyFunction(
const char cszParam1[],
BOOL bParam2 /* = TRUE */
);

4.8.代码段的注释
描述某个代码段的注释，可以给注释描述的代码段外围加上{}，帮助阅读。
例：

//代码段实现功能或意图描述
{
代码段
}