良好編程習慣的養成對於一個程序員的發展非常重要,而注釋對於一份程序來講又是一個必不可少的組成部分,今天來研究一下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:
*evision History:
*DateRel VerNotes
*XX/XX/XXXXX.X
*****************************************************************/
三、函數描述
函數的頭部應進行注釋,列出:函數的目的/功能、輸入參數、輸出參數、返回值、調用關系等。例如:
/*****************************************************************
*Function://函數名稱
*Description://函數功能,性能等的描述
*Calls://備貨單本函數調用的函數清單
*Called By://調用的本函數的清單
*Input://輸入參數說明,包括每個參數的作用、取值說明及參數間關系
*Output://輸出參數的說明
*Return://函數返回值的說明
*Others://其他說明
*****************************************************************/