程序員所要知道的編程規(guī)范、編碼規(guī)范

1、C/C+語(yǔ)言編碼規(guī)范文件狀態(tài)： 草稿 正式發(fā)布 正在修改文件標(biāo)識(shí)：編碼規(guī)范當(dāng)前版本：1.0作 者：劉文完成日期：2010-02-17上海涌能能源科技發(fā)展有限公司文檔修訂記錄版本編號(hào)或者更改記錄編號(hào)*變化狀態(tài)簡(jiǎn)要說(shuō)明日期變更人審核日期審核人*變化狀態(tài)：A增加，M修改，D刪除文檔審批信息職務(wù)簽字日期目 錄1. 目的42. 適用范圍43. 定義44. 職責(zé)45. 流程圖56. 內(nèi)容和要求56.1 基本原則56.2 布局66.2.1 文件布局66.2.2 基本格式96.2.3 對(duì)齊106.2.4 空行空格116.2.5 斷行136.2.6 預(yù)處理指令136.3 注釋136.4 命名規(guī)則186.5 變量

2、、常量、宏與類型226.5.1 變量與常量226.5.2 宏246.5.3 類型256.6 表達(dá)式與語(yǔ)句276.7 函數(shù)與過(guò)程316.7.1 參數(shù)316.7.2 返回值326.7.3 內(nèi)部實(shí)現(xiàn)336.7.4 函數(shù)調(diào)用356.8 可靠性366.8.1 內(nèi)存使用366.8.2 指針使用376.8.3 類和函數(shù)386.9 可測(cè)試性396.10 斷言與錯(cuò)誤處理407. 相關(guān)文件428. 記錄表單421 1. 目的 1.1 編寫(xiě)本標(biāo)準(zhǔn)的目的是為了統(tǒng)一公司軟件編程風(fēng)格，提高軟件源程序的可讀性、可靠性和可重用性，提高軟件源程序的質(zhì)量和可維護(hù)性，減少軟件維護(hù)成本，最終提高軟件產(chǎn)品生產(chǎn)力。1.2 本規(guī)范是針對(duì)C

3、、C+語(yǔ)言的編程規(guī)范，其它不同編程語(yǔ)言可以參照此規(guī)范執(zhí)行。本規(guī)范適用于公司所有產(chǎn)品的軟件源程序，同時(shí)考慮到不同產(chǎn)品和項(xiàng)目的實(shí)際開(kāi)發(fā)特性，本規(guī)范分成規(guī)則性和建議性兩種：對(duì)于規(guī)則性規(guī)范，要求所有軟件開(kāi)發(fā)人員嚴(yán)格執(zhí)行；對(duì)于建議性規(guī)范，各項(xiàng)目編程人員可以根據(jù)實(shí)際情況選擇執(zhí)行。本規(guī)范的示例都以C+語(yǔ)言描述。 1.3 本規(guī)范的內(nèi)容包括：基本原則、布局、注釋、命名規(guī)則、變量常量與類型、表達(dá)式與語(yǔ)句、函數(shù)與過(guò)程、可靠性、可測(cè)性、斷言與錯(cuò)誤處理等。 2 2. 適用范圍 2.1 本標(biāo)準(zhǔn)規(guī)定了C+語(yǔ)言的編程規(guī)范，而不是編程的技巧。 2.2 本標(biāo)準(zhǔn)適用于公司內(nèi)使用C+語(yǔ)言編碼的所有軟件。本規(guī)范自生效之日起，對(duì)以后新編

4、寫(xiě)的和修改的代碼有約束力。 3 3. 定義 下列術(shù)語(yǔ)和定義適用于本標(biāo)準(zhǔn)： 3.1 原則：編程時(shí)應(yīng)該堅(jiān)持的指導(dǎo)思想。 3.2 規(guī)則：編程時(shí)必須遵守的約定。 3.3 建議：編程時(shí)必須加以考慮的約定。 3.4 說(shuō)明：對(duì)此規(guī)則或建議的必要的解釋。 3.5 正例：對(duì)此規(guī)則或建議給出的正確例子。 3.6 反例：對(duì)此規(guī)則或建議給出的反面例子。 4 4. 職責(zé) 4.1 主任設(shè)計(jì)師負(fù)責(zé)此文件的制定和完善。 4.2 他設(shè)計(jì)師依照此文件執(zhí)行C+語(yǔ)言編碼。 5 5. 流程圖 無(wú)6 6. 內(nèi)容和要求 6.1 基本原則 6.1.1 編寫(xiě)程序是為人閱讀，其次才是計(jì)算機(jī)。 說(shuō)明：該原則是軟件開(kāi)發(fā)的基本要點(diǎn)，軟件生命周期貫穿于

5、產(chǎn)品的開(kāi)發(fā)、測(cè)試、生產(chǎn)、用戶使用、版本升級(jí)和后期維護(hù)等長(zhǎng)期過(guò)程，只有易讀、易維護(hù)的軟件代碼才具有生命力。 6.1.2 保持代碼的簡(jiǎn)明清晰，避免過(guò)分或刻意的追求編程技巧。 說(shuō)明：簡(jiǎn)單是最美。保持代碼的簡(jiǎn)單化是軟件工程化的基本要求。不要過(guò)分追求技巧，否則會(huì)降低程序的可讀性。 6.1.3 所有的代碼盡量遵循ANSI 標(biāo)準(zhǔn)。 說(shuō)明：所有的代碼盡可能遵循ANSI 標(biāo)準(zhǔn)，盡可能不使用ANSI未定義的或編譯器擴(kuò)展的功能。6.1.4 編程時(shí)首先以達(dá)到正確性為目的，其次再考慮效率。 說(shuō)明：編程首先考慮的是滿足正確性、健壯性、可維護(hù)性、可移植性等質(zhì)量因素，最后才考慮程序的效率和資源占用。 6.1.5 避免或少用全

6、局變量。 說(shuō)明：過(guò)多地使用全局變量，會(huì)導(dǎo)致模塊間的緊耦合，違反模塊化的要求。 6.1.6 盡可能重用代碼。 說(shuō)明：盡量選擇可借用的代碼，對(duì)其修改、優(yōu)化以達(dá)到自身使用要求。 6.1.7 團(tuán)隊(duì)合作。說(shuō)明：編程規(guī)范的使用要點(diǎn)在于提供一個(gè)開(kāi)發(fā)團(tuán)隊(duì)共同遵守的樣本，沒(méi)有所謂對(duì)和錯(cuò)。團(tuán)隊(duì)所有成員可以把精力集中在實(shí)現(xiàn)內(nèi)容而不是表現(xiàn)形式上。本文給出了主要的風(fēng)格規(guī)范，但個(gè)人的風(fēng)格也很重要，如果你在一個(gè)文件中新加的代碼和原有代碼風(fēng)格相去甚遠(yuǎn)的話，這就破壞了文件本身的整體美觀也影響閱讀，所以要盡量避免。 6.2 布局 程序布局的目的是展現(xiàn)程序良好的邏輯結(jié)構(gòu)，以提高程序的準(zhǔn)確性、連續(xù)性、可讀性、可維護(hù)性。更重要的是，統(tǒng)

7、一的程序布局和編程風(fēng)格，有助于提高整個(gè)項(xiàng)目的開(kāi)發(fā)質(zhì)量，提高開(kāi)發(fā)效率，降低開(kāi)發(fā)成本。同時(shí)，對(duì)于程序員來(lái)說(shuō)，養(yǎng)成良好的編程習(xí)慣有助于提高自己的編程水平，提高編程效率。 6.2.1 文件布局 【規(guī)則2-1-1】遵循統(tǒng)一的布局順序來(lái)書(shū)寫(xiě)頭文件 說(shuō)明：以下內(nèi)容如果某些節(jié)不需要，可以忽略。但是其它節(jié)要保持該次序。 頭文件布局:a) 文件頭注釋（參見(jiàn) “注釋”章節(jié)） b) #ifndef 文件名_H（全大寫(xiě)）（用來(lái)避免重復(fù)包含） #define 文件名_H c) 其它條件編譯選項(xiàng) d) #include（依次為標(biāo)準(zhǔn)庫(kù)頭文件、非標(biāo)準(zhǔn)庫(kù)頭文件） e) 與C+編譯器適應(yīng)extern “C”聲明前綴 f) 全局宏

8、g) 常量定義 h) 全局?jǐn)?shù)據(jù)類型 i) 類/結(jié)構(gòu)的聲明 j) 模板（template）（包括C+中的類模板和函數(shù)模板） k) 輸出函數(shù)部分 l) 與C+編譯器適應(yīng)extern “C”聲明前綴結(jié)束； m) 需要包含的內(nèi)聯(lián)函數(shù)定義文件 #endif【規(guī)則2-1-2】遵循統(tǒng)一的布局順序來(lái)書(shū)寫(xiě)實(shí)現(xiàn)文件 說(shuō)明：一個(gè)定義文件實(shí)現(xiàn)一組功能相關(guān)的函數(shù)接口和子函數(shù)接口，不能同時(shí)實(shí)現(xiàn)不同頭文件聲明的函數(shù)接口，它主要包含如下幾個(gè)部分：(規(guī)范不強(qiáng)求具體文件涵蓋下面所有內(nèi)容，對(duì)存在的內(nèi)容則應(yīng)按照以下順序排放；和頭文件相同的項(xiàng)目，要求同頭文件構(gòu)成部分相同)。 實(shí)現(xiàn)文件布局： a) 文件頭注釋（參見(jiàn) “注釋”章節(jié)） b)

9、 #include（依次為標(biāo)準(zhǔn)庫(kù)頭文件、非標(biāo)準(zhǔn)庫(kù)頭文件）將僅與實(shí)現(xiàn)相關(guān)的類、函數(shù)及數(shù)據(jù)的頭文件包含在實(shí)現(xiàn)文件里（而不是頭文件中）是一個(gè)非常好的編程習(xí)慣。這樣可以有效地屏蔽不應(yīng)該暴露的實(shí)現(xiàn)細(xì)節(jié)，將實(shí)現(xiàn)改變對(duì)其它模塊的影響降低到最少 。 c) 文件內(nèi)部使用的宏d) 常量定義e) 文件內(nèi)部使用的數(shù)據(jù)類型f) 外部可以使用的全局?jǐn)?shù)據(jù)定義部分g) 本地變量（即靜態(tài)全局變量）h) 局部函數(shù)原型(文件范圍內(nèi)的函數(shù)原型聲明)i) 類的實(shí)現(xiàn)j) 全局函數(shù)k) 局部函數(shù) l) 實(shí)現(xiàn)文件的編碼規(guī)則： 分割每個(gè)部分：在本地（靜態(tài)）定義和外部定義間，以及不同接口或不同類的實(shí)現(xiàn)之間，應(yīng)使用注釋塊（注釋塊見(jiàn)下面解釋）相互分

10、開(kāi)。 【規(guī)則2-1-3】使用注釋塊分離上面定義的節(jié) 正例： / * * 數(shù)據(jù)類型定義 * * / typedef unsigned char BOOLEAN; /* * 函數(shù)原型 * */ int HelloWorld(void); 【規(guī)則2-1-4】包含標(biāo)準(zhǔn)庫(kù)頭文件用尖括號(hào) ，包含非標(biāo)準(zhǔn)庫(kù)頭文件用雙引號(hào) “ ”正例： #include #include “MMS.h” 【規(guī)則2-1-5】遵循統(tǒng)一的風(fēng)格書(shū)寫(xiě)類(class)的定義及實(shí)現(xiàn) 說(shuō)明：類定義文件中類容按如下順序書(shū)寫(xiě)： a) 注釋頭與類聲明: 與文件一樣，每個(gè)類應(yīng)當(dāng)有一個(gè)注釋頭用來(lái)說(shuō)明該類的各個(gè)方面。類聲明換行緊跟在注釋頭后面，class

11、 關(guān)鍵字由行首開(kāi)始書(shū)寫(xiě)，后跟類名稱。界定符 和 ; 應(yīng)獨(dú)占一行，并與 class 關(guān)鍵字左對(duì)其。 b) 繼承: 基類直接跟在類名稱之后，不換行，訪問(wèn)說(shuō)明符（public, private, 或protected）不可省略。如：class CXXX : public CAAA, private CBBB / . ; c) 初始化列表：應(yīng)當(dāng)盡可能通過(guò)構(gòu)造函數(shù)的初始化列表來(lái)初始化成員和基類。初始化列表至少獨(dú)占一行，并且與構(gòu)造函數(shù)的定義保持4 個(gè)空格的縮進(jìn)。如： CXXX:CXXXX(IN int nA, IN bool bB): m_nA(nA), m_bB(bB) / . ; 初始化列表的書(shū)寫(xiě)順序

12、應(yīng)當(dāng)與對(duì)象的構(gòu)造順序一致，即：先按照聲明順序?qū)懟惓跏蓟?，再按照聲明順序?qū)懗蓡T初始化。 d) 嵌套的類聲明：在相應(yīng)的邏輯關(guān)系確實(shí)存在時(shí)，類聲明可以嵌套。嵌套類可以使用簡(jiǎn)單的單行注釋頭。 e) 公有屬性 f) 公有函數(shù) g) 保護(hù)屬性 h) 保護(hù)函數(shù) i) 私有屬性 j) 私有函數(shù) 訪問(wèn)說(shuō)明符（public, private, 或protected）應(yīng)該獨(dú)占一行，并與類聲明中的class關(guān)鍵字左對(duì)齊。k) 類實(shí)現(xiàn)文件內(nèi)容按如下順序書(shū)寫(xiě)： 構(gòu)造函數(shù)析構(gòu)函數(shù) 公有函數(shù) 保護(hù)函數(shù) 私有函數(shù) 【規(guī)則2-1-6】?jī)?nèi)聯(lián)函數(shù)定義文件 在內(nèi)聯(lián)函數(shù)較多的情況下，為了避免頭文件過(guò)長(zhǎng)、版面混亂，可以將所有的內(nèi)聯(lián)函數(shù)定

13、義移到一個(gè)單獨(dú)的文件中去，然后再用#include指令將它包含到類聲明的后面。這樣的文件稱為一個(gè)內(nèi)聯(lián)函數(shù)定義文件。 按照慣例，應(yīng)該將這個(gè)文件命名為“filename.inl”，其中“filename”與相應(yīng)的頭文件和實(shí)現(xiàn)文件相同。 內(nèi)聯(lián)函數(shù)定義文件由以下幾部分組成： 文件頭注釋：每?jī)?nèi)聯(lián)函數(shù)定義文件都應(yīng)該由一個(gè)規(guī)范的文件頭注釋作為開(kāi)始 內(nèi)聯(lián)函數(shù)定義：內(nèi)聯(lián)函數(shù)的實(shí)現(xiàn)體 6.2.2 基本格式 【規(guī)則2-2-1】程序中一行的代碼和注釋不能超過(guò)80列說(shuō)明：包括空格在內(nèi)不超過(guò)80 列。 【規(guī)則2-2-2】if、else、else if、for、while、do等語(yǔ)句自占一行，執(zhí)行語(yǔ)句不得緊跟其后。不論執(zhí)行

14、語(yǔ)句有多少都要加 。 說(shuō)明：這樣易于閱讀，也容易檢查錯(cuò)誤。 正例： if (varible1 varible2) varible1 = varible2; 反例：下面的代碼中執(zhí)行語(yǔ)句緊跟在if條件之后，而且沒(méi)有加，違反規(guī)則。 if (varible1 ”這類操作符前后不加空格。正例： !bValue iValue +iCount *strSource &fSum aiNumberi = 5; tBox.dWidth tBox-dWidth 【規(guī)則2-4-3】多元運(yùn)算符和它們的操作數(shù)之間至少需要一個(gè)空格。 正例： fValue = fOldValue; fTotal + fValue iNumb

15、er += 2; 【規(guī)則2-4-4】函數(shù)名之后不要留空格。 說(shuō)明：函數(shù)名后緊跟左括號(hào)(，以與關(guān)鍵字區(qū)別。 【規(guī)則2-4-6】注釋符與注釋內(nèi)容之間要用一個(gè)空格進(jìn)行分隔。 正例： /* 注釋內(nèi)容 */ 注釋內(nèi)容反例：/*注釋內(nèi)容*/ /注釋內(nèi)容 6.2.5 斷行 【規(guī)則2-5-1】長(zhǎng)表達(dá)式（超過(guò)80 列）要在低優(yōu)先級(jí)操作符處拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要進(jìn)行適當(dāng)?shù)目s進(jìn)，使排版整齊。 說(shuō)明：條件表達(dá)式的續(xù)行在第一個(gè)條件處對(duì)齊。 for循環(huán)語(yǔ)句的續(xù)行在初始化條件語(yǔ)句處對(duì)齊。 函數(shù)調(diào)用和函數(shù)聲明的續(xù)行在第一個(gè)參數(shù)處對(duì)齊。 賦值語(yǔ)句的續(xù)行應(yīng)在賦值號(hào)處對(duì)齊。 正例： if

16、(iFormat = CH_A_Format_M) & (iOfficeType = CH_BSC_M) / 條件表達(dá)式的續(xù)行在第一個(gè)條件處對(duì)齊 DoSomething(); for (long_initialization_statement; long_condiction_statement;/ for循環(huán)語(yǔ)句續(xù)行在初始化條件語(yǔ)句處對(duì)齊long_update_statement) DoSomething();/ 函數(shù)聲明的續(xù)行在第一個(gè)參數(shù)處對(duì)齊BYTE ReportStatusCheckPara(HWND hWnd, BYTE ucCallNo,BYTE ucStatusReportNo

17、);/ 賦值語(yǔ)句的續(xù)行應(yīng)在賦值號(hào)處對(duì)齊fTotalBill = fTotalBill + faCustomerPurchasesiID+ fSalesTax(faCustomerPurchasesiID); 6.2.6 預(yù)處理指令 【規(guī)則2-6-1】預(yù)處理指令不要縮進(jìn)，從行首開(kāi)始。即使預(yù)處理指令位于縮進(jìn)代碼塊中，指令也應(yīng)從行首開(kāi)始。 6.3 注釋 注釋有助于理解代碼，有效的注釋是指在代碼的功能、邏輯層次上進(jìn)行注釋，提供有用、額外的信息，而不是代碼表面意義的簡(jiǎn)單重復(fù)。 【規(guī)則3-1】多行注釋采用“/* */”，單行注釋采用“/ ”。 【規(guī)則3-2】一般情況下，源程序有效注釋量必須在30以上 說(shuō)明

18、：注釋的原則是有助于對(duì)程序的閱讀理解，注釋不宜太多也不能太少，注釋語(yǔ)言必須準(zhǔn)確、易懂、簡(jiǎn)潔。有效的注釋是指在代碼的功能、邏輯層次上進(jìn)行注釋，提供有用、額外的信息。 【規(guī)則3-3】注釋使用中文。說(shuō)明：對(duì)于特殊要求的可以使用英文注釋，如工具不支持中文或國(guó)際化版本時(shí)?！疽?guī)則3-4】文件頭部必須進(jìn)行注釋，包括：.h 文件、.cpp 文件、.inc 文件、.def 文件、編譯說(shuō)明文件.cfg等。 說(shuō)明：注釋必須列出：版權(quán)信息、文件標(biāo)識(shí)、內(nèi)容摘要、版本號(hào)、作者、完成日期、修改信息等。正例： 下面是文件頭部的中文注釋： /* * 版權(quán)所有 (C)2010, 上海思源弘瑞自動(dòng)化股份公司 * * 文件名稱： /

19、 文件名 * 內(nèi)容摘要： / 簡(jiǎn)要描述本文件的內(nèi)容，包括主要模塊、函數(shù)及其功能的說(shuō)明 * 其它說(shuō)明： / 其它內(nèi)容的說(shuō)明 * 當(dāng)前版本： / 輸入當(dāng)前版本 * 作 者： / 輸入作者名字及單位 * 完成日期： / 輸入完成日期，例：2010年5月15日* * 修改記錄1：/ 修改歷史記錄，包括修改日期、修改者及修改內(nèi)容 * 修改日期： * 版 本 號(hào)： * 修 改 人： * 修改內(nèi)容： * 修改記錄2： */ 下面是文件頭部的英文注釋： /* * Copyright (C) 2010, SHR Corporation. * * File Name: / 文件名 （注釋對(duì)齊） * Descrip

20、tion: / 簡(jiǎn)要描述本文件的內(nèi)容，完成的主要功能 * Others: / 其它內(nèi)容的說(shuō)明 * Version: / 輸入當(dāng)前版本 * Author: / 輸入作者名字及單位 * Date: / 輸入完成日期，例：2010-05-15 * * History 1: / 修改歷史記錄，包括修改日期、修改者及修改內(nèi)容 * Date: * Version: * Author: * Modification: * History 2: */ 【規(guī)則3-5】函數(shù)頭部應(yīng)進(jìn)行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、修改信息等。 說(shuō)明：注釋必須列出：函數(shù)名稱、功能描述、輸入?yún)?shù)、輸出參數(shù)、

21、返 回 值、修改信息等。正例： 下面是函數(shù)頭部的中文注釋： /* * 函數(shù)名稱： / 函數(shù)名稱 * 功能描述： / 函數(shù)功能、性能等的描述 * 輸入?yún)?shù)： / 輸入?yún)?shù)說(shuō)明，包括每個(gè)參數(shù)的作用、取值說(shuō)明及參數(shù)間關(guān)系 * 輸出參數(shù)： / 對(duì)輸出參數(shù)的說(shuō)明。 * 返 回 值： / 函數(shù)返回值的說(shuō)明 * 其它說(shuō)明： / 其它說(shuō)明 * 修改日期 版本號(hào) 修改人 修改內(nèi)容 * -* 2010/08/01 V1.0 XXXX XXXX */ 下面是函數(shù)頭部的英文注釋： /* * Function: / 函數(shù)名稱（注釋對(duì)齊） * Description: / 函數(shù)功能、性能等的描述 * Input: / 輸

22、入?yún)?shù)說(shuō)明，包括每個(gè)參數(shù)的作用、取值說(shuō)明以及參數(shù)間關(guān)系 * Output: / 對(duì)輸出參數(shù)的說(shuō)明 * Return: / 函數(shù)返回值的說(shuō)明 * Others: / 其它說(shuō)明 * Modify Date Version Author Modification * -* 2010/08/01 V1.0 XXXX XXXX */ 【規(guī)則3-6】包含在 中代碼塊的結(jié)束處應(yīng)加注釋，便于閱讀。特別是多分支、多重嵌套的條件語(yǔ)句或循環(huán)語(yǔ)句。說(shuō)明：此時(shí)注釋可以用英文，方便查找對(duì)應(yīng)的語(yǔ)句。正例： void Main() If() while() /* end of while() */ / 指明該條while 語(yǔ)

23、句結(jié)束 /* end of if() */ / 指明是if語(yǔ)句結(jié)束 /* end of void main（）*/ / 指明函數(shù)的結(jié)束【規(guī)則3-7】保證代碼和注釋的一致性。修改代碼同時(shí)修改相應(yīng)的注釋，不再有用的注釋要?jiǎng)h除。 【規(guī)則3-8】注釋?xiě)?yīng)與其描述的代碼相近，對(duì)代碼的注釋?xiě)?yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開(kāi)。說(shuō)明：在使用縮寫(xiě)時(shí)或之前，應(yīng)對(duì)縮寫(xiě)進(jìn)行必要的說(shuō)明。 正例： 如下書(shū)寫(xiě)比較結(jié)構(gòu)清晰：/* 獲得子系統(tǒng)索引 */ iSubSysIndex = aDataiIndex.iSysIndex; /* 代碼段1注釋 */ 代碼段1

24、/* 代碼段2注釋 */ 代碼段2 反例1： 如下例子注釋與描述的代碼相隔太遠(yuǎn)：/* 獲得子系統(tǒng)索引 */ iSubSysIndex = aDataiIndex.iSysIndex; 反例2：如下例子注釋不應(yīng)放在所描述的代碼下面：iSubSysIndex = aDataiIndex.iSysIndex; /* 獲得子系統(tǒng)索引 */ 反例3： 如下例子，顯得代碼與注釋過(guò)于緊湊：/* 代碼段1注釋 */ 代碼段1 /* 代碼段2注釋 */ 代碼段2 【規(guī)則3-9】全局變量要有詳細(xì)的注釋，包括對(duì)其功能、取值范圍、訪問(wèn)信息及訪問(wèn)時(shí)注意事項(xiàng)等的說(shuō)明。 正例： /* * 變量作用：（錯(cuò)誤狀態(tài)碼） * 變量

25、范圍：例如0 - SUCCESS 1 ERROR * 訪問(wèn)說(shuō)明：（訪問(wèn)的函數(shù)以及方法） */ BYTE g_btTranErrorCode; 【規(guī)則3-10】注釋與所描述內(nèi)容進(jìn)行同樣的縮排。說(shuō)明：可使程序排版整齊，并方便注釋的閱讀與理解。正例： 如下注釋結(jié)構(gòu)比較清晰 int DoSomething(void) /* 代碼段1注釋 */ 代碼段1 /* 代碼段2注釋 */ 代碼段2 【規(guī)則3-11】對(duì)分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）必須編寫(xiě)注釋。說(shuō)明：這些語(yǔ)句往往是程序?qū)崿F(xiàn)某一特殊功能的關(guān)鍵，對(duì)于維護(hù)人員來(lái)說(shuō)，良好的注釋有助于更好的理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。 建議3-1通過(guò)對(duì)函數(shù)或過(guò)程、

26、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼結(jié)構(gòu)，使代碼成為自注釋的。 說(shuō)明：清晰準(zhǔn)確的函數(shù)、變量命名，可增加代碼的可讀性，減少不必要的注釋?！疽?guī)則3-12】注釋掉整塊的代碼使用#if 0 和#endif。 【規(guī)則3-13】避免在一行代碼或表達(dá)式的中間插入注釋。6.4 命名規(guī)則 好的命名規(guī)則能極大地增加可讀性和可維護(hù)性。同時(shí)，對(duì)于一個(gè)由多個(gè)個(gè)體共同完成的項(xiàng)目來(lái)說(shuō)，統(tǒng)一的命名約定也是一項(xiàng)必不可少的內(nèi)容。【規(guī)則4-1】標(biāo)識(shí)符要采用英文單詞或其組合，便于記憶和閱讀，切忌使用漢語(yǔ)拼音來(lái)命名。說(shuō)明：標(biāo)識(shí)符應(yīng)當(dāng)直觀且可以拼讀，可望文知義，避免使人產(chǎn)生誤解。程序中的英文單詞一般不要太復(fù)雜，用詞應(yīng)當(dāng)準(zhǔn)確?！疽?guī)則4

27、-2】標(biāo)識(shí)符只能由26個(gè)英文字母、10個(gè)數(shù)字及下劃線來(lái)組成.除非針對(duì)硬件的驅(qū)動(dòng)程序或操作系統(tǒng)相關(guān)的等底層程序外,嚴(yán)格禁止使用連續(xù)的下劃線，下劃線也不能出現(xiàn)在標(biāo)識(shí)符頭或結(jié)尾（預(yù)編譯開(kāi)關(guān)除外）。 說(shuō)明：這樣做的目的是為了使程序易讀。因?yàn)?variable_name 和 variable_name 很難區(qū)分，下劃線符號(hào)_若出現(xiàn)在標(biāo)識(shí)符頭或結(jié)尾，容易與不帶下劃線_的標(biāo)識(shí)符混淆?！疽?guī)則4-3】標(biāo)識(shí)符的命名應(yīng)當(dāng)符合“min-length & max-information”原則 說(shuō)明：較短的單詞可通過(guò)去掉“元音”形成縮寫(xiě)，較長(zhǎng)的單詞可取單詞的頭幾個(gè)字母形成縮寫(xiě)，一些單詞有大家公認(rèn)的縮寫(xiě)，常用單詞的縮寫(xiě)必須

28、統(tǒng)一。協(xié)議中的單詞的縮寫(xiě)與協(xié)議保持一致。對(duì)于某個(gè)系統(tǒng)使用的專用縮寫(xiě)應(yīng)該在某處做統(tǒng)一說(shuō)明。 正例：如下單詞的縮寫(xiě)能夠被大家認(rèn)可： temp 可縮寫(xiě)為 tmp ； flag 可縮寫(xiě)為 flg ； statistic 可縮寫(xiě)為 stat ； increment 可縮寫(xiě)為 inc ； message 可縮寫(xiě)為 msg ； 【規(guī)則4-4】程序中不要出現(xiàn)僅靠大小寫(xiě)區(qū)分的相似的標(biāo)識(shí)符【規(guī)則4-5】用正確的反義詞組命名具有互斥意義的變量或相反動(dòng)作的函數(shù)等。 說(shuō)明：下面是一些在軟件中常用的反義詞組。 add/remove;begin/end; create/destroy;insert/delete;first

29、/last;get/release; increment/decrement; put/get;add/delete;lock/unlock; open/close;min/max;old/new;start/stop; next/previous;source/target;show/hide;send/receive; source/destination; cut/paste;up/down【規(guī)則4-6】宏、常量名都要使用大寫(xiě)字母, 用下劃線 _ 分割單詞。預(yù)編譯開(kāi)關(guān)的定義使用下劃線 _ 開(kāi)始。 正例：如 DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE 等等。 【規(guī)則

30、4-7】變量名長(zhǎng)度應(yīng)小于31 個(gè)字符，以保持與ANSI C 標(biāo)準(zhǔn)一致。不得取單個(gè)字符（如i、j、k等）作為變量名，但是局部循環(huán)變量除外。 說(shuō)明：變量，尤其是局部變量，如果用單個(gè)字符表示，很容易出錯(cuò)（如l 誤寫(xiě)成1）,而編譯時(shí)又檢查不出，則有可能增加排錯(cuò)時(shí)間。過(guò)長(zhǎng)的變量名會(huì)增加工作量，會(huì)使程序的邏輯流程變得模糊，給修改帶來(lái)困難，所以應(yīng)當(dāng)選擇精煉、意義明確的名字，才能簡(jiǎn)化程序語(yǔ)句，改善對(duì)程序功能的理解。 【規(guī)則4-8】程序中局部變量不能與全局變量重名。 說(shuō)明：盡管局部變量和全局變量的作用域不同而不會(huì)發(fā)生語(yǔ)法錯(cuò)誤，但容易使人誤解。 【規(guī)則4-9】 使用一致的前綴來(lái)區(qū)分變量的作用域，變量類型分為全局、

31、靜態(tài)、局部等，它們的標(biāo)識(shí)分別為g、s、l。對(duì)于局部變量應(yīng)當(dāng)省略，此時(shí)需去掉“_”。 說(shuō)明：變量活動(dòng)范圍前綴規(guī)范如下： g_：全局變量s_：模塊內(nèi)靜態(tài)變量空：局部變量不加范圍前綴【規(guī)則4-10】使用一致的小寫(xiě)類型指示符作為前綴來(lái)區(qū)分變量的類型。說(shuō)明：常用變量類型前綴列表如下： a(arr)： 數(shù)組，array of TYPE b ： BOOL c ： char d ： double dw： DWORD 或 unsigned long f ： float h ： HANDLE i ： int l ： long n ：unsigned int p ： pointer sz(str) ： 字符串 t

32、： 結(jié)構(gòu)類型 uc ： unsigned char 或 BYTE w ： unsigned short 或 WORD 以上前綴可以進(jìn)一步組合,在進(jìn)行組合時(shí)，數(shù)組和指針類型的前綴指示符必須放在變量類型前綴的首位。 針對(duì)鏈表類型的變量，數(shù)據(jù)類型不在變量前綴中體現(xiàn)，而是在變量主體標(biāo)識(shí)結(jié)束后添加List/Head 標(biāo)識(shí)，或者_(dá)list/_head。 示例： 局部無(wú)符號(hào)八位整數(shù)tripCount 的命名：nTripCount；無(wú)符號(hào)整數(shù)數(shù)組可以寫(xiě)成：nTripCounts；靜態(tài)掛起請(qǐng)求數(shù)據(jù)結(jié)構(gòu)鏈表：s_ptPendReqList or s_ptPendReq_head；【規(guī)則4-11】完整的變量名應(yīng)由前

33、綴+變量名主體組成，變量名的主體應(yīng)當(dāng)使用“名詞”或者“形容詞名詞”，且所有單詞均以大寫(xiě)字母開(kāi)始其余以小些字母書(shū)寫(xiě)，單詞連續(xù)書(shū)寫(xiě)。說(shuō)明：1) 各種前綴字符可能組合使用，在這種情況下，各前綴順序?yàn)椋鹤兞孔饔糜蚯熬Y、變量類型前綴。2) 縮寫(xiě)的單詞按照慣例是大小寫(xiě)的，整個(gè)單詞全部按照慣例書(shū)寫(xiě)。 正例： float g_fValue; /類型為浮點(diǎn)數(shù)的全局變量 char *pcOldChar; /類型為字符指針的局部變量 s_ptPendReqList； /*靜態(tài)掛起請(qǐng)求數(shù)據(jù)結(jié)構(gòu)鏈表, 符合規(guī)范 */ 智能設(shè)備IED 的名稱：szIEDName; /* 符合規(guī)范 */ 反例： s_ptPend_req_

34、list；/* 不符合規(guī)范 pend和req 應(yīng)該合在一起書(shū)寫(xiě) */s_ptPendreq_list； /* 不符合規(guī)范 req應(yīng)該以大寫(xiě)字母開(kāi)頭 */szIedName; /* 不符合規(guī)范 */ 【規(guī)則4-12】 類的成員函數(shù)名用大寫(xiě)字母開(kāi)頭的一個(gè)或多個(gè)單詞組合而成，且應(yīng)當(dāng)使用“動(dòng)詞”或者“動(dòng)詞名詞”（動(dòng)賓詞組）。 說(shuō)明：1) 函數(shù)名力求清晰、明了，通過(guò)函數(shù)名就能夠判斷函數(shù)的主要功能。函數(shù)名中不同意義字段之間不要用下劃線連接，而要把每個(gè)字段的首字母大寫(xiě)以示區(qū)分。函數(shù)命名采用大小寫(xiě)字母結(jié)合的形式，但專有名詞不受限制。2) 函數(shù)接口名稱由“函數(shù)前綴標(biāo)識(shí)”+“_”+“函數(shù)主體標(biāo)識(shí)”+“_”+“修飾

35、語(yǔ)標(biāo)識(shí)”組成。3) 函數(shù)前綴標(biāo)識(shí)是指函數(shù)接口所在的模塊名稱，函數(shù)前綴標(biāo)識(shí)部分首字母大寫(xiě)，后面字符采用小寫(xiě)的英文字符表示。4) 主體標(biāo)識(shí)部分以一個(gè)大寫(xiě)字母的單詞開(kāi)始，并以“_”和函數(shù)前綴標(biāo)識(shí)分開(kāi)，如果函數(shù)主體標(biāo)識(shí)部分多于一個(gè)單詞，應(yīng)將幾個(gè)單詞寫(xiě)到一起，后面的單詞都以大寫(xiě)字母開(kāi)頭。 注：縮寫(xiě)的單詞按照慣例是大小寫(xiě)的，整個(gè)單詞全部按照慣例書(shū)寫(xiě)。示例： ST_RET Ai_var_ParseDataValues（）; /* ai_var 模塊實(shí)現(xiàn)的解析數(shù)據(jù)結(jié)構(gòu)數(shù)據(jù)值接口 */ 5) 對(duì)于封裝的庫(kù)接口，可以使用庫(kù)縮寫(xiě)代替函數(shù)實(shí)現(xiàn)的模塊名作為函數(shù)前綴標(biāo)識(shí)，并且需要在回調(diào)函數(shù)或者擴(kuò)展函數(shù)的函數(shù)前綴標(biāo)識(shí)前添加

36、“U_”予以標(biāo)識(shí)。 示例：ST_RET Iec61850_GetDataValues（）; /* ac_read 模塊實(shí)現(xiàn)的IEC61850 通訊平臺(tái)庫(kù)客戶端讀數(shù)據(jù)值接口 */ST_VOID U_iec61850_command(); /* IEC61850 通訊平臺(tái)庫(kù)在服務(wù)器端提供給應(yīng)用者的操作命令擴(kuò)展接口 */ 6) 為充分表述函數(shù)操作的限定，可以在函數(shù)主體標(biāo)識(shí)后添加修飾語(yǔ)標(biāo)識(shí)。示例： MVL_NET_INFO *Ac_srvm_GetNetInfo_byIEDName（）; /* ac_srvm 模塊實(shí)現(xiàn)的通過(guò)裝置名稱獲取通道函數(shù)接口 */ 建議：虛函數(shù)習(xí)慣以“Do”開(kāi)頭，如：DoRef

37、resh()；事件處理函數(shù)習(xí)慣以單詞“On”開(kāi)頭；回調(diào)函數(shù)以CallBack 開(kāi)頭?！疽?guī)則4-13】 類名采用大小寫(xiě)結(jié)合的方法。在構(gòu)成類名的單詞之間不用下劃線，類名在開(kāi)頭加上C，后跟一個(gè)或多個(gè)單詞。為便于界定，每個(gè)單詞的首字母要大寫(xiě)。類的成員變量統(tǒng)一在前面加m_ 前綴。 建議：類的命名應(yīng)當(dāng)用名詞或形容詞名詞的形式。 正例：void CMyClass:SetValue(int iWidth, int iHeight) m_iWidth = iWidth;m_iHeight = iHeight; 建議4-1 盡量避免名字中出現(xiàn)數(shù)字編號(hào)，如Value1、Value2等，除非邏輯上的確需要編號(hào)。 【規(guī)

38、則4-14】 C結(jié)構(gòu)體只是一種將一組數(shù)據(jù)捆綁在一起的方式，名稱全部由大寫(xiě)字母組成，單詞間使用下劃線界定。 【規(guī)則4-15】枚舉、聯(lián)合及typedef 語(yǔ)句都是定義新類型的簡(jiǎn)單手段，生成的類型名由全大寫(xiě)字母組成，單詞間通過(guò)下劃線來(lái)界定，如：ERROR_TYPE。枚舉值應(yīng)全部大寫(xiě)，單詞間以下劃線相連。 【規(guī)則4-16】常量名由類型前綴全大寫(xiě)字母組成，單詞間通過(guò)下劃線來(lái)界定，如： nMAX_BUFFER 【規(guī)則4-17】名空間的名稱不應(yīng)該過(guò)長(zhǎng)，使用縮寫(xiě)的形式來(lái)命名，言簡(jiǎn)意賅。命名空間的名稱全小寫(xiě)，命名基于項(xiàng)目/子系統(tǒng)名稱。 【規(guī)則4-18】 文件名要全部小寫(xiě)，可以包含短線（-）。C+文件以.cpp結(jié)

39、尾，C文件以.c結(jié)尾。頭文件以.h結(jié)尾。 【規(guī)則4-19】若一個(gè)模塊僅由一個(gè)定義文件和頭文件組成，則頭文件和定義文件必須有相同的名字（除了擴(kuò)展名）。允許一個(gè)頭文件聲明的函數(shù)接口被不同的定義文件實(shí)現(xiàn)，但不允許一個(gè)定義文件實(shí)現(xiàn)不同頭文件中聲明的函數(shù)接口。 6.5 變量、常量、宏與類型 變量、常量和數(shù)據(jù)類型是程序編寫(xiě)的基礎(chǔ)，它們的正確使用直接關(guān)系到程序設(shè)計(jì)的成敗，變量包括全局變量、局部變量和靜態(tài)變量，常量包括數(shù)據(jù)常量和指針常量，類型包括系統(tǒng)的數(shù)據(jù)類型和自定義數(shù)據(jù)類型。 6.5.1 變量與常量【規(guī)則5-1-1】定義全局變量時(shí)必須仔細(xì)分析，明確其含義、作用、取值范圍及與其它全局變量間的關(guān)系。說(shuō)明：全局變

40、量關(guān)系到程序的結(jié)構(gòu)框架，對(duì)于全局變量的理解關(guān)系到對(duì)整個(gè)程序能否正確理解，所以在對(duì)全局變量聲明的同時(shí)，應(yīng)對(duì)其含義、作用及取值范圍進(jìn)行詳細(xì)地注釋說(shuō)明，若有必要還應(yīng)說(shuō)明與其它變量的關(guān)系。 【規(guī)則5-1-2】明確全局變量與操作此全局變量的函數(shù)或過(guò)程的關(guān)系。 說(shuō)明：全局變量與函數(shù)的關(guān)系包括：創(chuàng)建、修改及訪問(wèn)。明確過(guò)程操作變量的關(guān)系后，將有利于程序的進(jìn)一步優(yōu)化、單元測(cè)試、系統(tǒng)聯(lián)調(diào)以及代碼維護(hù)等。這種關(guān)系的說(shuō)明可在注釋或文檔中描述。 【規(guī)則5-1-3】一個(gè)變量有且只有一個(gè)功能，不能把一個(gè)變量用作多種用途。 說(shuō)明：一個(gè)變量只用來(lái)表示一個(gè)特定功能，不能把一個(gè)變量作多種用途，即同一變量取值不同時(shí)，其代表的意義也不

41、同。正例： WORD DelRelTimeQue(T_TCB *ptTcb )WORD wValue;WORD wLocate;wLocate = 3;wValue = DeleteFromQue(wLocate);return wValue;反例： WORD DelRelTimeQue(T_TCB *ptTcb) WORD wLocate; wLocate = 3; wLocate = DeleteFromQue(wLocate); / wLocate 具有兩種功能。return wLocate; 【規(guī)則5-1-4】循環(huán)語(yǔ)句與判斷語(yǔ)句中，不允許對(duì)其它變量進(jìn)行計(jì)算與賦值。 說(shuō)明：循環(huán)語(yǔ)句只完成

42、循環(huán)控制功能，if 語(yǔ)句只完成邏輯判斷功能，不能完成計(jì)算賦值功能。正例：do 處理語(yǔ)句 cInput = GetChar(); while (cInput = 0); 反例：do 處理語(yǔ)句 while(cInput = GetChar();【規(guī)則5-1-5】宏定義中如果包含表達(dá)式或變量，表達(dá)式和變量必須用小括號(hào)括起來(lái)。說(shuō)明：在宏定義中，對(duì)表達(dá)式和變量使用括號(hào)，可以避免可能發(fā)生的計(jì)算錯(cuò)誤. 正例：#define HANDLE(A, B) ( A ) / ( B )反例：#define HANDLE(A, B) (A / B)建議5-1-1對(duì)于全局變量通過(guò)統(tǒng)一的函數(shù)訪問(wèn)。說(shuō)明：可以避免訪問(wèn)全局變量

43、時(shí)引起的錯(cuò)誤。正例：T_Student g_tStudent; T_Student GetStudentValue(void)T_Student tStudentValue;獲取g_tStudent 的訪問(wèn)權(quán)tStudentValue = g_tStudent;釋放g_tStudent 的訪問(wèn)權(quán)return tStudentValue;BYTE SetStudentValue(const T_Student *ptStudentValue)BYTE ucIfSuccess;ucIfSuccess = 0; 獲取g_tStudent 的訪問(wèn)權(quán)g_tStudent = *ptStudentValu

44、e ;釋放g_tStudent 的訪問(wèn)權(quán)return ucIfSuccess;建議5-1-2盡量使用const 說(shuō)明常量數(shù)據(jù)，對(duì)于宏定義的常數(shù)，必須指出其類型。正例：const int MAX_COUNT = 100;#define MAX_COUNT (int)100反例：#define MAX_COUNT 1006.5.2 宏【規(guī)則 5-2-1】用宏定義表達(dá)式時(shí)，要使用完備的括號(hào)。 示例：如下定義的宏都存在一定的風(fēng)險(xiǎn)。 #define RECTANGLE_AREA( a, b ) a * b #define RECTANGLE_AREA( a, b ) (a * b)#define RECTANGLE_AREA( a, b ) (a) * (b)正確的定義應(yīng)為：#define RECTANGLE_AREA( a, b ) (a) * (b) 【規(guī)則 5-2-2】將宏所定義的多條表達(dá)式放在大括號(hào)中。 示例：下面宏定義不符合要求#define INTI_RECT_VALUE( a, b )a = 0;b = 0;正確的寫(xiě)法應(yīng)為：#define INTI_RECT_VALUE( a, b ) a = 0;b = 0;【規(guī)則 5-2-3】使用宏時(shí)，不允許參數(shù)發(fā)生變化。 示例：如下用法可能導(dǎo)致錯(cuò)誤。#define SQUARE( a ) (a