2011軟考軟件設(shè)計師：C語言代碼規(guī)范問題(3)
1.3 程序注釋
1.3.1程序注釋是程序員與日后的程序讀者之間通信的重要手段之一，注釋分為文件注釋、函數(shù)注釋和功能注釋。
1.3.2正規(guī)程序的注釋應(yīng)注意：
——注釋行的數(shù)量占到整個源程序的1/3到1/2。
1.3.3文件注釋位于整個源程序的最開始部分，注釋后空兩行開始程序正文。它包括：
——程序標(biāo)題。
——目的、功能說明。
——文件作者、***修改日期等說明。
例：
./
(空一行)
標(biāo)題： Demo.c
功能： 測試VxWorks的各種系統(tǒng)調(diào)用。
說明：
該程序測試各種VxWorks的系統(tǒng)調(diào)用函數(shù)。包括任務(wù)(taks)的創(chuàng)建、掛起及任務(wù)間通過信號燈實現(xiàn)同步，通過消息隊列進行通訊。
程序創(chuàng)建了兩個任務(wù)：一個高優(yōu)先級的任務(wù)和一個低優(yōu)先級的任務(wù)。兩個任務(wù)間通過一個二進制的信號燈進行同步，通過消息隊列進行通訊。
當(dāng)前版本： x.x
修改信息： 2000.06.05 John， Initial Version
2000.07.05 Tom， Bug xxxx fixed
/
(空2行，開始程序正文)
1.3.4 函數(shù)注釋通常置于每函數(shù)或過程的開頭部分，它應(yīng)當(dāng)給出函數(shù)或過程的整體說明對于理解程序本身具有引導(dǎo)作用。一般包括如下條目：
——模塊標(biāo)題。
——有關(guān)本模塊功能和目的的說明。
——調(diào)用格式
——接口說明：包括輸入、輸出、返回值、異常。
——算法。如果模塊中采用了一些復(fù)雜的算法。
例：
file：//(注釋開頭應(yīng)和上一函數(shù)空兩行)
(注釋開頭與上一函數(shù)***一行間隔兩行)
/
標(biāo)題：assignmentComplete
功能：BSC=%26gt;MSC消息生成函數(shù)，生成assignment_complete指配完成消息(BSMAP消息) .
格式：
int assignmentComplete(int iCellId， int iServiceChannnelNum， char pszMSGData) throw(exception1， exception2)
輸入：
int iCellId： MS所在的小區(qū)識別
iCellId取值：0x00-——0xff .4.
Q/ECC/BJ 010—2001
int iServiceChannnelNum：MS所占的業(yè)務(wù)信道號碼
輸出：
char pszMSGData：指配完成消息數(shù)據(jù)
返回值： 0x00正常
異常：exception1異常情況1， exception2異常情況2
/
( 注釋后直接開始程序正文，不空行。)
1.3.5 功能性注釋嵌在源程序體中，用于描述其后的語句或程序段做什么工作，也就是解釋下面要做什么，或是執(zhí)行了下面的語句會怎么樣。而不要解釋下面怎么做，因為解釋怎么做常常與程序本身是重復(fù)的。
例： /把 amount 加到 total中/
total = amount + total;
這樣的注釋僅僅是重復(fù)了下面的程序，對于理解它的工作并沒有什么作用。而下面的注釋，有助于讀者理解。
/將每月的銷售額amount加到年銷售額total中/
total = amount + total;
【編輯推薦】
