華爲軟件編程規範學習(二)--註釋

華爲軟件編程規範學習(二)--註釋

轉自：http://blog.csdn.net/ce123_zhouwei/article/details/8885964

2-1：一般情況下，源程序有效註釋量必須在20％以上

說明：註釋的原則是有助於對程序的閱讀理解，在該加的地方都加了，註釋不宜太多也不能太少，註釋語言必須準確、易懂、簡潔。

2-2：說明性文件（如頭文件.h文件、.inc文件、.def文件、編譯說明文件.cfg等）頭部應進行註釋，註釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、與其它文件的關係、修改日誌等，頭文件的註釋中還應有函數功能簡要說明

示例：下面這段頭文件的頭註釋比較標準，當然，並不侷限於此格式，但上述信息建議要包含在內。

/*************************************************
  Copyright (C),1988-1999, Huawei Tech. Co., Ltd.
  Filename:      // 文件名
  Author:      Version:        Date: // 作者、版本及完成日期
  Description:    // 用於詳細說明此程序文件完成的主要功能，與其他模塊
                 // 或函數的接口，輸出值、取值範圍、含義及參數間的控
                 // 制、順序、獨立或依賴等關係
  Others:         // 其它內容的說明
  FunctionList:  // 主要函數列表，每條記錄應包括函數名及功能簡要說明
    1.....
  History:        // 修改歷史記錄列表，每條修改記錄應包括修改日期、修改
                 // 作者及修改內容簡述
    1.Date:
      Author:
      Modification:
    2....
*************************************************/

2-3：源文件頭部應進行註釋，列出：版權說明、版本號、生成日期、作者、模塊目的/功能、主要函數及其功能、修改日誌等。

示例：下面這段源文件的頭註釋比較標準，當然，並不侷限於此格式，但上述信息建議要包含在內。

/************************************************************
  Copyright (C),1988-1999, Huawei Tech. Co., Ltd.
  FileName:test.cpp
  Author:        Version:          Date:
  Description:     // 模塊描述
  Version:         // 版本信息
  FunctionList:   // 主要函數及其功能
    1.-------
  History:         // 歷史修改記錄
     <author>  <time>   <version >  <desc>
     David    96/10/12    1.0     build this moudle
***********************************************************/

說明：Description一項描述本文件的內容、功能、內部各部分之間的關係及本文件與其它文件關係等。History是修改歷史記錄列表，每條修改記錄應包括修改日期、修改者及修改內容簡述。

2-4：函數頭部應進行註釋，列出：函數的目的/功能、輸入參數、輸出參數、返回值、調用關係（函數、表）等

示例：下面這段函數的註釋比較標準，當然，並不侷限於此格式，但上述信息建議要包含在內。

/*************************************************
 Function:       // 函數名稱
 Description:    // 函數功能、性能等的描述
 Calls:          // 被本函數調用的函數清單
 CalledBy:      // 調用本函數的函數清單
 TableAccessed: // 被訪問的表（此項僅對於牽扯到數據庫操作的程序）
 TableUpdated:  // 被修改的表（此項僅對於牽扯到數據庫操作的程序）
 Input:          // 輸入參數說明，包括每個參數的作
                 // 用、取值說明及參數間關係。
 Output:         // 對輸出參數的說明。
 Return:         // 函數返回值的說明
 Others:         // 其它說明
*************************************************/

2-5：邊寫代碼邊註釋，修改代碼同時修改相應的註釋，以保證註釋與代碼的一致性。不再有用的註釋要刪除

2-6：註釋的內容要清楚、明瞭，含義準確，防止註釋二義性

說明：錯誤的註釋不但無益反而有害。

2-7：避免在註釋中使用縮寫，特別是非常用縮寫

說明：在使用縮寫時或之前，應對縮寫進行必要的說明。

2-8：註釋應與其描述的代碼相近，對代碼的註釋應放在其上方或右方（對單條語句的註釋）相鄰位置，不可放在下面，如放於上方則需與其上面的代碼用空行隔開

示例：如下例子不符合規範。

repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
/* get replicate subsystem index and net indicator */

應如下書寫

/* get replicate subsystem index and net indicator */
repssn_ind =ssn_data[index].repssn_index;
repssn_ni =ssn_data[index].ni;

2-9：對於所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時都必須加以註釋，說明其物理含義。變量、常量、宏的註釋應放在其上方相鄰位置或右方

示例：

/* active statistictask number */
#defineMAX_ACT_TASK_NUMBER 1000
#defineMAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

2-10：數據結構聲明(包括數組、結構、類、枚舉等)，如果其命名不是充分自注釋的，必須加以註釋。對數據結構的註釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的註釋放在此域的右方

示例：可按如下形式說明枚舉/數據/聯合結構。

/* sccp interfacewith sccp user primitive message name */
enum  SCCP_USER_PRIMITIVE
{
   N_UNITDATA_IND, /* sccp notify sccp user unit data come */
   N_NOTICE_IND,   /* sccp notify user the No.7 network can not */
                   /* transmission this message */
   N_UNITDATA_REQ, /* sccp user's unit data transmission request*/
};

2-11：全局變量要有較詳細的註釋，包括對其功能、取值範圍、哪些函數或過程存取它以及存取時注意事項等的說明

示例：

/* The ErrorCode whenSCCP translate */
/* Global Titlefailure, as follows */      // 變量作用、含義
/* 0 － SUCCESS   1 － GT Table error */
/* 2 － GT error  Others － no use */       // 變量取值範圍
/* only  function SCCPTranslate() in */
/* this modual canmodify it,  and  other */
/* module can visitit through call */
/* the  functionGetGTTransErrorCode() */    // 使用方法
BYTE g_GTTranErrorCode;

2-12：註釋與所描述內容進行同樣的縮排

說明：可使程序排版整齊，並方便註釋的閱讀與理解。

示例：如下例子，排版不整齊，閱讀稍感不方便。

void example_fun(void )
{
/* code one comments*/
   CodeBlock One

       /* code two comments */
   CodeBlock Two
}

應改爲如下佈局。

void example_fun(void )
{
    /*code one comments */
   CodeBlock One
    /*code two comments */
   CodeBlock Two
}

2-13：將註釋與其上面的代碼用空行隔開

示例：如下例子，顯得代碼過於緊湊。

/* code one comments*/
program code one
/* code two comments*/
program code two

應如下書寫

/* code one comments*/
program code one

/* code two comments*/
program code two

2-14：對變量的定義和分支語句（條件分支、循環語句等）必須編寫註釋

說明：這些語句往往是程序實現某一特定功能的關鍵，對於維護人員來說，良好的註釋幫助更好的理解程序，有時甚至優於看設計文檔。

2-15：對於switch語句下的case語句，如果因爲特殊情況需要處理完一個case後進入下一個case處理，必須在該case語句處理完、下一個case語句前加上明確的註釋

說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏break語句。

示例（注意斜體加粗部分）：

caseCMD_UP:
   ProcessUp();
   break;
case CMD_DOWN:
    ProcessDown();
   break;
case CMD_FWD:
   ProcessFwd();
   if (...)
   {
        ...
        break;
   }
   else
   {
       ProcessCFW_B();   // now jump into case CMD_A
   }
caseCMD_A:
   ProcessA();
   break;
caseCMD_B:
   ProcessB();
   break;
case CMD_C:
   ProcessC();
    break;
caseCMD_D:
   ProcessD();
   break;
...

其他

2-1：避免在一行代碼或表達式的中間插入註釋

說明：除非必要，不應在代碼或表達中間插入註釋，否則容易使代碼可理解性變差。

2-2：通過對函數或過程、變量、結構等正確的命名以及合理地組織代碼的結構，使代碼成爲自注釋的

說明：清晰準確的函數、變量等的命名，可增加代碼可讀性，並減少不必要的註釋。

2-3：在代碼的功能、意圖層次上進行註釋，提供有用、額外的信息

說明：註釋的目的是解釋代碼的目的、功能和採用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重複註釋信息。

示例：如下注釋意義不大。

/* if receive_flag isTRUE */
if (receive_flag)

而如下的註釋則給出了額外有用的信息。

/* if mtp receive amessage from links */
if (receive_flag)

2-4：在程序塊的結束行右方加註釋標記，以表明某程序塊的結束

說明：當代碼段較長，特別是多重嵌套時，這樣做可以使代碼更清晰，更便於閱讀。

示例：參見如下例子。

if (...)
{
   //program code
   while (index < MAX_INDEX)
    {
       // program code
    }/* end of while (index < MAX_INDEX) */ // 指明該條while語句結束
} /* end of  if(...)*/ // 指明是哪條if語句結束

2-5：註釋格式儘量統一，建議使用“/* …… */”

2-6：註釋應考慮程序易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能用非常流利準確的英文表達

說明：註釋語言不統一，影響程序易讀性和外觀排版，出於對維護人員的考慮，建議使用中文。