C/C++ 註釋規範

1 源文件頭部註釋

Ø 列出：版權、作者、編寫日期和描述。

Ø 示例：

[cpp] view plaincopy

1. /************************************************* 
2. Copyright:bupt 
3. Author: 
4. Date:2010-08-25 
5. Description:描述主要實現的功能 
6. **************************************************/  

 

每行不要超過80個字符的寬度。

2 函數頭部註釋

/功能、輸入參數、輸出參數、返回值、調用關係（函數、表）等。

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

要包含在內。

 

[cpp] view plaincopy

1. /************************************************* 
2. Function:       // 函數名稱 
3. Description:    // 函數功能、性能等的描述 
4. Calls:          // 被本函數調用的函數清單 
5. Table Accessed: // 被訪問的表（此項僅對於牽扯到數據庫操作的程序） 
6. Table Updated: // 被修改的表（此項僅對於牽扯到數據庫操作的程序） 
7. Input:          // 輸入參數說明，包括每個參數的作 
8.                   // 用、取值說明及參數間關係。 
9. Output:         // 對輸出參數的說明。 
10. Return:         // 函數返回值的說明 
11. Others:         // 其它說明 
12. *************************************************/  

 

 

3 數據結構聲明的註釋(包括數組、結構、類、枚舉等)

如果其命名不是充分自注釋的，必須加以註釋。對數據結構的註釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的註釋放在此域的右方。

 

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

 

[cpp] view plaincopy

1. /* sccp interface with sccp user primitive message name */  
2. enum SCCP_USER_PRIMITIVE  
3. {  
4.     N_UNITDATA_IND, /* sccp notify sccp user unit data come */  
5.     N_NOTICE_IND,   /* sccp notify user the No.7 network can not */  
6.                     /* transmission this message */  
7.     N_UNITDATA_REQ, /* sccp user's unit data transmission request*/  
8. };  

 

4 全局變量的註釋

Ø 包括對其功能、取值範圍、哪些函數或過程存取它以及存取時注意事項等的說明。

 

示例：

[cpp] view plaincopy

1. /* The ErrorCode when SCCP translate */  
2. /* Global Title failure, as follows */      // 變量作用、含義  

 

 

 

 

 

5 對代碼的註釋

註釋總是加在程序的需要一個概括性說明或不易理解或易理解錯的地方。註釋語言應該簡練、易懂而又含義準確，避免二義性；所採用的語種首選是中文，如有輸入困難、編譯環境限制或特殊需求也可採用英文。註釋應與其描述的代碼相近，對代碼的註釋統一放在其上方，避免在一行代碼或表達式中間使用註釋。上方註釋與其上面的代碼用空行隔開（較緊湊的代碼除外）。

注意：註釋應與所描述內容進行同樣的縮進。