C語言注釋風格

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

　　規則:

1：一般情況下，源程式有效注釋量必須在20％以上。

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

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

示例：下面這段頭檔案的頭注釋比較标準，當然，并不局限于此格式，但上述資訊建議要包含在内。

3： 源檔案頭部應進行注釋，列出：版權說明、版本号、生成日期、作者、子產品目的/功能、主要函數及其功能、修改日志等。

示例：下面這段源檔案的頭注釋 比較标準，當然，并不局限于此格式，但上述資訊建議要包含在内。

說 明：Description一項描述本檔案的内容、功能、内部各部分之間的關系及本檔案與其它檔案關系等。History是修改曆史記錄清單，每條修改記 錄應包括修改日期、修改者及修改内容簡述。

4：函數頭部應進行注釋，列出：函數的目的/功能、輸入參數、輸出參數、傳回值、調用關系（函 數、表）等。

示例：下面這段函數的注釋比較标準，當然，并不局限于此格式，但上述資訊建議要包含在内。

5： 邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一緻性。不再有用的注釋要删除。

6：注釋的内容要清楚、明了，含義準确，防止注 釋二義性。

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

7：避免在注釋中使用縮寫，特别是非常用縮寫。

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

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

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

例1：

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;

應如下書寫

repssn_ind = ssn_data[index].repssn_index;

repssn_ni = ssn_data[index].ni;

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

示 例：

#define MAX_ACT_TASK_NUMBER 1000

#define MAX_ACT_TASK_NUMBER 1000

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

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

enum SCCP_USER_PRIMITIVE

{

N_UNITDATA_IND,

N_NOTICE_IND,

N_UNITDATA_REQ,

};

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

示 例：

// 變量作用、含義

// 變量取值範圍

// 使用方法

BYTE g_GTTranErrorCode;

12：注釋與所描述内容進行同樣的縮排。

說明：可使程式排版整齊，并友善注釋的閱讀與了解。

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

void example_fun( void )

{

CodeBlock One

CodeBlock Two

}

應改為如下布局。

void example_fun( void )

{

CodeBlock One

CodeBlock Two

}

13：将注釋與其上面的代碼用空行隔開。

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

program code one

program code two

應如下書寫

program code one

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)

而如下的注釋則給 出了額外有用的資訊。

if (receive_flag)

4：在程式塊的結束行右方加注釋标記，以表明某程式塊的結束。

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

示例：參見如下例子。

if (...)

{

// program code

while (index < MAX_INDEX)

{

// program code

} // 指明該條while語句結束

} // 指明是哪條if語句結束

5：注釋格式盡量統一，建議使用""。

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

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