1、源文件頭部注釋
列出:版權、作者、編寫日期和描述。
示例:
/*************************************************
Copyright:radi
Author:
Date:2018-08-14
Description:描述主要實現的功能
**************************************************/
每行不要超過80個字符的寬度。
2、 函數頭部注釋
功能、輸入參數、輸出參數、返回值、調用關系(函數、表)等。
示例:下面這段函數的注釋比較標准,當然,並不局限於此格式,但上述信息建議
要包含在內。
/*************************************************
Function: // 函數名稱
Description: // 函數功能、性能等的描述
Calls: // 被本函數調用的函數清單
Table Accessed: // 被訪問的表(此項僅對於牽扯到數據庫操作的程序)
Table Updated: // 被修改的表(此項僅對於牽扯到數據庫操作的程序)
Input: // 輸入參數說明,包括每個參數的作
// 用、取值說明及參數間關系。
Output: // 對輸出參數的說明。
Return: // 函數返回值的說明
Others: // 其它說明
*************************************************/
3、 數據結構聲明的注釋(包括數組、結構、類、枚舉等)
如果其命名不是充分自注釋的,必須加以注釋。對數據結構的注釋應放在其上方相鄰位置,不可放在下面;對結構中的每個域的注釋放在此域的右方。
示例:可按如下形式說明枚舉/數據/聯合結構
/* 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*/
};
4 、全局變量的注釋
包括對其功能、取值范圍、哪些函數或過程存取它以及存取時注意事項等的說明。
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */ // 變量作用、含義
5 、對代碼的注釋
注釋總是加在程序的需要一個概括性說明或不易理解或易理解錯的地方。注釋語言應該簡練、易懂而又含義准確,避免二義性;所采用的語種首選是中文,如有輸入困難、編譯環境限制或特殊需求也可采用英文。注釋應與其描述的代碼相近,對代碼的注釋統一放在其上方,避免在一行代碼或表達式中間使用注釋。上方注釋與其上面的代碼用空行隔開(較緊湊的代碼除外)。
注意:注釋應與所描述內容進行同樣的縮進。
Mercury_Lc發現有個神奇的注釋,竟然是藍色的。
/**加油!一定不要放棄。*/