C語言中注釋的示例分析

這篇文章給大家分享的是有關(guān)C語言中注釋的示例分析的內(nèi)容。小編覺得挺實用的，因此分享給大家做個參考，一起跟隨小編過來看看吧。

錯誤，在C語言中注釋部分對程序的運(yùn)行結(jié)果不產(chǎn)生任何影響，它可以出現(xiàn)在程序的任何位置。在C語言中有兩種注釋方式：一種是以“/*”開始、以“*/”結(jié)束的塊注釋；一種是以“//”開始、以換行符結(jié)束的單行注釋。

C語言中的注釋

在編寫C語言源代碼時，應(yīng)該多使用注釋，這樣有助于對代碼的理解。在C語言中有兩種注釋方式：

• 一種是以/*開始、以*/結(jié)束的塊注釋（block comment）；

• 另一種是以//開始、以換行符結(jié)束的單行注釋（line comment）。

可以使用/*和*/分隔符來標(biāo)注一行內(nèi)的注釋，也可以標(biāo)注多行的注釋。例如，在下列的函數(shù)原型中，省略號的意思是 open() 函數(shù)有第三個參數(shù)，它是可選參數(shù)。注釋解釋了這個可選參數(shù)的用法：

int open( const char *name, int mode, … /* int permissions */ );

可以使用//插入整行的注釋，或者將源代碼寫成兩列分欄的格式，程序在左列，注釋在右列：

const double pi = 3.1415926536;       // pi是—個常量

在 C99 標(biāo)準(zhǔn)中，單行注釋正式加入C語言，但是大部分編譯器在 C99 之前就已經(jīng)開始支持這種用法。有時候，其被稱作“C++風(fēng)格”的注釋，但實際上，其源自于C的前身 BCPL。

注釋的位置

在C語言中注釋部分對程序的運(yùn)行結(jié)果不產(chǎn)生任何影響，它可以出現(xiàn)在程序的任何位置。

示例：

int/*....*/i;                                   //正確

char* s="abcdefgh   //hijklmn";                  //正確

in/*...*/ti;                                    //錯誤注釋會被空格替換

//注意：             /*...*/不能嵌套 ，/*總是與離他最近的*/匹配

 y=x/*p           //       該語句由于沒有找到*/ 會報錯
 
//要實現(xiàn)以上功能  可以用y=x/(*p)或y=x/ *p代替

注釋規(guī)范

2-1：一般情況下，源程序有效注釋量必須在20％以上。

說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準(zhǔn)確、易懂、簡潔。

2-2：文件頭部應(yīng)進(jìn)行注釋，注釋必須列出：版權(quán)說明、版本號、生成日期、作者、內(nèi)容、功能、修改日志等。

示例：下面這段頭文件的頭注釋比較標(biāo)準(zhǔn)，當(dāng)然，并不局限于此格式，但上述信息建議要包含在內(nèi)。

/*****************************************************************************
Copyright: 1988-1999, Huawei Tech. Co., Ltd.
File name: 文件名
Description: 用于詳細(xì)說明此程序文件完成的主要功能，與其他模塊或函數(shù)的接口，輸出值、取值范圍、含義及參數(shù)間的控制、順序、獨(dú)立或依賴等關(guān)系
Author: 作者
Version: 版本
Date: 完成日期
History: 修改歷史記錄列表， 每條修改記錄應(yīng)包括修改日期、修改者及修改內(nèi)容簡述。
*****************************************************************************/

2-3：函數(shù)頭部應(yīng)進(jìn)行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào)用關(guān)系（函數(shù)、表）等。

示例：下面這段函數(shù)的注釋比較標(biāo)準(zhǔn)，當(dāng)然，并不局限于此格式，但上述信息建議要包含在內(nèi)。

/*************************************************
Function: // 函數(shù)名稱
Description: // 函數(shù)功能、性能等的描述
Calls: // 被本函數(shù)調(diào)用的函數(shù)清單
Called By: // 調(diào)用本函數(shù)的函數(shù)清單
Table Accessed: // 被訪問的表（此項僅對于牽扯到數(shù)據(jù)庫操作的程序）
Table Updated: // 被修改的表（此項僅對于牽扯到數(shù)據(jù)庫操作的程序）
Input: // 輸入?yún)?shù)說明，包括每個參數(shù)的作// 用、取值說明及參數(shù)間關(guān)系。
Output: // 對輸出參數(shù)的說明。
Return: // 函數(shù)返回值的說明
Others: // 其它說明
********************************************/

2-4：邊寫代碼邊注釋，修改代碼同時修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除。

2-5：注釋的內(nèi)容要清楚、明了，含義準(zhǔn)確，防止注釋二義性。說明：錯誤的注釋不但無益反而有害。

2-6：注釋應(yīng)與其描述的代碼相近，對代碼的注釋應(yīng)放在其上方或右方（對單條語句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。

示例：如下例子不符合規(guī)范。

例1：

/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;

例2：

repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
/* get replicate sub system index and net indicator */

應(yīng)如下書寫

/* get replicate sub system index and net indicator */
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;

2-7：對于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時都必須加以注釋，說明其物理含義。變量、常量、宏的注釋應(yīng)放在其上方相鄰位置或右方。

示例：

/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

2-8：數(shù)據(jù)結(jié)構(gòu)聲明(包括數(shù)組、結(jié)構(gòu)、類、枚舉等)，如果其命名不是充分自注釋的，必須加以注釋。對數(shù)據(jù)結(jié)構(gòu)的注釋應(yīng)放在其上方相鄰位置，不可放在下面；對結(jié)構(gòu)中的每個域的注釋放在此域的右方。

示例：可按如下形式說明枚舉/數(shù)據(jù)/聯(lián)合結(jié)構(gòu)。

/* 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 */
};

2-9：全局變量要有較詳細(xì)的注釋，包括對其功能、取值范圍、哪些函數(shù)或過程存取它以及存取時注意事項等的說明。

示例：

/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */ // 變量作用、含義
/* 0 － SUCCESS 1 － GT Table error */
/* 2 － GT error Others － no use */ // 變量取值范圍
/* only function SCCPTranslate() in */
/* this modual can modify it, and other */
/* module can visit it through call */
/* the function GetGTTransErrorCode() */ // 使用方法
BYTE g_GTTranErrorCode;

2-10：注釋與所描述內(nèi)容進(jìn)行同樣的縮排。

說明：可使程序排版整齊，并方便注釋的閱讀與理解。示例：如下例子，排版不整齊，閱讀稍感不方便。

void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}

應(yīng)改為如下布局。

void example_fun( void )
{
/* code one comments */
CodeBlock One
/* code two comments */
CodeBlock Two
}

2-11：避免在一行代碼或表達(dá)式的中間插入注釋。

說明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。

2-12：通過對函數(shù)或過程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的。

說明：清晰準(zhǔn)確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。

2-13：在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息。

說明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重復(fù)注釋信息。

示例：如下注釋意義不大。

/* if receive_flag is TRUE */
if (receive_flag)

而如下的注釋則給出了額外有用的信息。

/* if mtp receive a message from links */
if (receive_flag)

2-14：在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束。

說明：當(dāng)代碼段較長，特別是多重嵌套時，這樣做可以使代碼更清晰，更便于閱讀。示例：參見如下例子。

if (…)
{
// program code
while (index < MAX_INDEX)
{
// program code
} /* end of while (index < MAX_INDEX) */ // 指明該條while 語句結(jié)束
} /* end of if (…)*/ // 指明是哪條if 語句結(jié)束

2-15：注釋格式盡量統(tǒng)一，建議使用“/*…… */”。

2-16：注釋應(yīng)考慮程序易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能用非常流利準(zhǔn)確的英文表達(dá)。

說明：注釋語言不統(tǒng)一，影響程序易讀性和外觀排版，出于對維護(hù)人員的考慮，建議使用中文。

感謝各位的閱讀！關(guān)于“C語言中注釋的示例分析”這篇文章就分享到這里了，希望以上內(nèi)容可以對大家有一定的幫助，讓大家可以學(xué)到更多知識，如果覺得文章不錯，可以把它分享出去讓更多的人看到吧！