良好程式設計習慣的養成對于一個程式員的發展非常重要,而注釋對于一份程式來講又是一個必不可少的組成部分,今天來研究一下C語言程式的注釋風格。
注釋是源碼程式中非常重要的一部分,一般情況下,源程式有效注釋量必須在15%以上。
注釋的原則是有助于對程式的閱讀了解,是以注釋語言必須準确、易懂、簡潔,注釋不宜太多也不能太少,注釋的内容要清楚、明了、含義準确,防止注釋二義性,該加的地方一定要加,但不必要的地方一定不要加。
一、子產品描述
子產品描述中應該包括子產品名、版本号、生成日期、作者、内容、功能、與其它檔案的關系、修改日志等等。例如:
Module Name:
Module Date:
Module Auth:
Description:
Others:
Revision History:
Date Rel Ver Notes:
XX/XX/XXXX X.X
二、頭檔案描述
頭檔案一般包含了資料結構的定義,函數原型的說明,宏定義等等,不許包含函數體和變量實體,檔案名使用預設的字尾.h,頭檔案的注釋如下:
/*****************************************************************
* Module Name:
* Module Date:
* Module Auth:
* Description:
* Others:
* Revision History:
* Date Rel Ver Notes:
* XX/XX/XXXXX.X
*****************************************************************/
三、函數描述
函數的頭部應進行注釋,列出:函數的目的/功能、輸入參數、輸出參數、傳回值、調用關系等。例如:
/*****************************************************************
* Function://函數名稱
* Description://函數功能,性能等的描述
* Calls://備貨單本函數調用的函數清單
* Called By://調用的本函數的清單
* Input://輸入參數說明,包括每個參數的作用、取值說明及參數間關系
* Output://輸出參數的說明
* Return://函數傳回值的說明
* Others://其他說明
*****************************************************************/