C語言中注釋的示例分析

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

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

C語言中的注釋

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

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

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

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

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

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

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

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

注釋的位置

在C語言中注釋部分對程序的運行結果不產生任何影響，它可以出現在程序的任何位置。

示例：

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

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

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

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

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

注釋規范

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

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

2-2：文件頭部應進行注釋，注釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、修改日志等。

示例：下面這段頭文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內。

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

2-3：函數頭部應進行注釋，列出：函數的目的/功能、輸入參數、輸出參數、返回值、調用關系（函數、表）等。

示例：下面這段函數的注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內。

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

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

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

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

示例：如下例子不符合規范。

例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 */

應如下書寫

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

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

示例：

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

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

示例：可按如下形式說明枚舉/數據/聯合結構。

/* 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：全局變量要有較詳細的注釋，包括對其功能、取值范圍、哪些函數或過程存取它以及存取時注意事項等的說明。

示例：

/* 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：注釋與所描述內容進行同樣的縮排。

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

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

應改為如下布局。

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

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

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

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

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

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

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

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

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

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

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

2-14：在程序塊的結束行右方加注釋標記，以表明某程序塊的結束。

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

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

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

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

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

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