C語言註釋規範

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


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

2-2：文件頭部應進行註釋，註釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、修改日誌等。


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


/*****************************************************************************

Copyright: 1988-1999, Huawei Tech. Co., Ltd.

File name: 文件名

Description: 用於詳細說明此程序文件完成的主要功能，與其他模塊或函數的接口，輸出值、取值範圍、含義及參數間的控制、順序、獨立或依賴等關係

Author: 作者

Version: 版本

Date: 完成日期

History: 修改歷史記錄列表， 每條修改記錄應包括修改日期、修改者及修改內容簡述。

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


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

/*************************************************

Function: // 函數名稱

Description: // 函數功能、性能等的描述

Calls: // 被本函數調用的函數清單

Called By: // 調用本函數的函數清單

Table Accessed: // 被訪問的表（此項僅對於牽扯到數據庫操作的程序）

Table Updated: // 被修改的表（此項僅對於牽扯到數據庫操作的程序）

Input: // 輸入參數說明，包括每個參數的作// 用、取值說明及參數間關係。

Output: // 對輸出參數的說明。

Return: // 函數返回值的說明

Others: // 其它說明

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

2-5：註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。說明：錯誤的註釋不但無益反而有害。

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


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

例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;

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


示例：

/ active statistic task number /

#define MAX_ACT_TASK_NUMBER 1000

#define MAX_ACT_TASK_NUMBER 1000 / active statistic task number /

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


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

/ 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/

};

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


示例：

/ 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;

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


說明：可使程序排版整齊，並方便註釋的閱讀與理解。示例：如下例子，排版不整齊，閱讀稍感不方便。

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-11：避免在一行代碼或表達式的中間插入註釋。


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

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


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

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


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


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

/ if receive_flag is TRUE /

if (receive_flag)


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

/ if mtp receive a message from links /

if (receive_flag)

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


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

if (…)

{

// program code

while (index < MAX_INDEX)

{

// program code

} / end of while (index < MAX_INDEX) / // 指明該條while 語句結束

} / end of if (…)/ // 指明是哪條if 語句結束

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

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


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