C語言程式設計規範-註釋

規則:
1：一般情況下，源程式有效註釋量必須在20％以上。
    說明：註釋的原則是有助於對程式的閱讀理解，在該加的地方都加了，註釋不宜太多也不能太少，註釋語言必須準確、易懂、簡潔。
2：說明性檔案（如標頭檔案.h檔案、.inc檔案、.def檔案、編譯說明檔案.cfg等）頭部應進行註釋，註釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、與其它檔案的關係、修改日誌等，標頭檔案的註釋中還應有函式功能簡要說明。

示例：下面這段標頭檔案的頭註釋比較標準，當然，並不侷限於此格式，但上述資訊建議要包含在內。
/*************************************************
Copyright (C), 1988-1999, Tech. Co., Ltd.
File name: // 檔名
Author:
Version:
Date: // 作者、版本及完成日期
Description: // 用於詳細說明此程式檔案完成的主要功能，與其他模組
// 或函式的介面，輸出值、取值範圍、含義及引數間的控
// 制、順序、獨立或依賴等關係
Others: // 其它內容的說明
Function List: // 主要函式列表，每條記錄應包括函式名及功能簡要說明
1. ....
History: // 修改歷史記錄列表，每條修改記錄應包括修改日期、修改
// 者及修改內容簡述
1. Date:
Author:
Modification:
2. ...
*************************************************/

3：原始檔頭部應進行註釋，列出：版權說明、版本號、生成日期、作者、模組目的/功能、主要函式及其功能、修改日誌等。

示例：下面這段原始檔的頭註釋比較標準，當然，並不侷限於此格式，但上述資訊建議要包含在內。
/************************************************************
Copyright (C), 1988-1999, Tech. Co., Ltd.
FileName: test.cpp
Author:
Version :
Date:
Description: // 模組描述
Version: // 版本資訊
Function List: // 主要函式及其功能
1. -------
History: // 歷史修改記錄
<author> <time> <version > <desc>
David 96/10/12 1.0 build this moudle
***********************************************************/
說明：Description一項描述本檔案的內容、功能、內部各部分之間的關係及本檔案與其它檔案關係等。History是修改歷史記錄列表，每條修改記錄應包括修改日期、修改者及修改內容簡述。

4：函式頭部應進行註釋，列出：函式的目的/功能、輸入引數、輸出引數、返回值、呼叫關係（函式、表）等。

示例：下面這段函式的註釋比較標準，當然，並不侷限於此格式，但上述資訊建議要包含在內。
/*************************************************
Function: // 函式名稱
Description: // 函式功能、效能等的描述
Calls: // 被本函式呼叫的函式清單
Called By: // 呼叫本函式的函式清單
Table Accessed: // 被訪問的表（此項僅對於牽扯到資料庫操作的程式）
Table Updated: // 被修改的表（此項僅對於牽扯到資料庫操作的程式）
Input: // 輸入引數說明，包括每個引數的作
// 用、取值說明及引數間關係。
Output: // 對輸出引數的說明。
Return: // 函式返回值的說明
Others: // 其它說明
*************************************************/

5：邊寫程式碼邊註釋，修改程式碼同時修改相應的註釋，以保證註釋與程式碼的一致性。不再有用的註釋要刪除。
6：註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。
說明：錯誤的註釋不但無益反而有害。
7：避免在註釋中使用縮寫，特別是非常用縮寫。
說明：在使用縮寫時或之前，應對縮寫進行必要的說明。
8：註釋應與其描述的程式碼相近，對程式碼的註釋應放在其上方或右方（對單條語句的註釋）相鄰位置，不可放在下面，如放於上方則需與其上面的程式碼用空行隔開。

示例：如下例子不符合規範。
例1：
/* get replicate sub system index and net indicator */

repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
例2：
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
/* get replicate sub system index and net indicator */
應如下書寫
/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;

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

示例：
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

10：資料結構宣告(包括陣列、結構、類、列舉等)，如果其命名不是充分自注釋的，必須加以註釋。對資料結構的註釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的註釋放在此域的右方。

示例：可按如下形式說明列舉/資料/聯合結構。
/* sccp interface with 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*/

};

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

示例：
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */ // 變數作用、含義
/* 0 － SUCCESS 1 － GT Table error */
/* 2 － GT error Others － no use */ // 變數取值範圍
/* only function SCCPTranslate() in */
/* this modual can modify it, and other */
/* module can visit it through call */
/* the function GetGTTransErrorCode() */ // 使用方法
BYTE g_GTTranErrorCode;

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

}

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

14：對變數的定義和分支語句（條件分支、迴圈語句等）必須編寫註釋。
說明：這些語句往往是程式實現某一特定功能的關鍵，對於維護人員來說，良好的註釋幫助更好的理解程式，有時甚至優於看設計文件。
15：對於switch語句下的case語句，如果因為特殊情況需要處理完一個case後進入下一個case處理，必須在該case語句處理完、下一個case 語句前加上明確的註釋。
說明：這樣比較清楚程式編寫者的意圖，有效防止無故遺漏break語句。

示例（注意斜體加粗部分）：
case CMD_UP:
    ProcessUp();
    break;
case CMD_DOWN:
    ProcessDown();
    break;

case CMD_FWD:

     ProcessFwd();

    if (...)
    {
        ...
        break;
    }
    else
    {
        ProcessCFW_B(); // now jump into case CMD_A
    }

case CMD_A:
    ProcessA();
    break;
case CMD_B:
    ProcessB();
    break;
case CMD_C:
     ProcessC();
    break;
case CMD_D:
    ProcessD();
    break;
...

建議:
1：避免在一行程式碼或表示式的中間插入註釋。
說明：除非必要，不應在程式碼或表達中間插入註釋，否則容易使程式碼可理解性變差。
2：通過對函式或過程、變數、結構等正確的命名以及合理地組織程式碼的結構，使程式碼成為自注釋的。
說明：清晰準確的函式、變數等的命名，可增加程式碼可讀性，並減少不必要的註釋。
3：在程式碼的功能、意圖層次上進行註釋，提供有用、額外的資訊。
說明：註釋的目的是解釋程式碼的目的、功能和採用的方法，提供程式碼以外的資訊，幫助讀者理解程式碼，防止沒必要的重複註釋資訊。
示例：如下注釋意義不大。
/* if receive_flag is TRUE */
if (receive_flag)

而如下的註釋則給出了額外有用的資訊。
/* if mtp receive a message from links */
if (receive_flag)
4：在程式塊的結束行右方加註釋標記，以表明某程式塊的結束。
說明：當代碼段較長，特別是多重巢狀時，這樣做可以使程式碼更清晰，更便於閱讀。
示例：參見如下例子。
if (...)
{
    // program code

    while (index < MAX_INDEX)
    {
        // program code
    } /* end of while (index < MAX_INDEX) */ // 指明該條while語句結束
} /* end of if (...)*/ // 指明是哪條if語句結束
5：註釋格式儘量統一，建議使用"/* …… */"。
6：註釋應考慮程式易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能用非常流利準確的英文表達。
說明：註釋語言不統一，影響程式易讀性和外觀排版，出於對維護人員的考慮，建議使用中文。