項(xiàng)目管理文檔7-軟件編程規(guī)范.doc

硬件開發(fā)部軟件編程規(guī)范 C/C+發(fā)布 實(shí)施 目 次前 言II1范圍12術(shù)語(yǔ)和定義12.1原則12.2規(guī)則12.3建議12.4說(shuō)明12.5正例12.6反例13基本原則14布局24.1文件布局24.2基本格式54.3對(duì)齊64.4空行空格84.5斷行95注 釋106命名規(guī)則15前 言編寫本標(biāo)準(zhǔn)的目的是為了統(tǒng)一硬件開發(fā)部軟件編程風(fēng)格，提高軟件源程序的可讀性、可靠性和可重用性，提高軟件源程序的質(zhì)量和可維護(hù)性，減少軟件維護(hù)成本，最終提高軟件產(chǎn)品生產(chǎn)力。本規(guī)范是針對(duì)C/C+語(yǔ)言的編程規(guī)范，其它不同編程語(yǔ)言可以參照此規(guī)范執(zhí)行。本規(guī)范適用于硬件開發(fā)部所有產(chǎn)品的軟件源程序，同時(shí)考慮到不同產(chǎn)品和項(xiàng)目的實(shí)際開發(fā)特性，本規(guī)范分成規(guī)則性和建議性兩種：對(duì)于規(guī)則性規(guī)范，要求所有軟件開發(fā)人員嚴(yán)格執(zhí)行；對(duì)于建議性規(guī)范，各項(xiàng)目編程人員可以根據(jù)實(shí)際情況選擇執(zhí)行。本規(guī)范的示例都以C/C+語(yǔ)言描述。本規(guī)范的內(nèi)容包括：基本原則、布局、注釋、命名規(guī)則等。自本標(biāo)準(zhǔn)實(shí)施之日起，以后新編寫的和修改的代碼均應(yīng)執(zhí)行本標(biāo)準(zhǔn)。本標(biāo)準(zhǔn)由硬件開發(fā)部提出。本標(biāo)準(zhǔn)起草部門：開發(fā)部。本標(biāo)準(zhǔn)于2010年5月首次發(fā)布。 II軟件編程規(guī)范 C/C+1 范圍 本標(biāo)準(zhǔn)規(guī)定了C/C+語(yǔ)言的編程規(guī)范。 本標(biāo)準(zhǔn)適用于部門內(nèi)使用C/C+語(yǔ)言編碼的所有軟件。本規(guī)范自生效之日起，對(duì)以后新編寫的和修改的代碼有約束力。2 術(shù)語(yǔ)和定義下列術(shù)語(yǔ)和定義適用于本標(biāo)準(zhǔn)。2.1 原則編程時(shí)應(yīng)該堅(jiān)持的指導(dǎo)思想。2.2 規(guī)則編程時(shí)必須遵守的約定。2.3 建議編程時(shí)必須加以考慮的約定。2.4 說(shuō)明對(duì)此規(guī)則或建議的必要的解釋。2.5 正例對(duì)此規(guī)則或建議給出的正確例子。2.6 反例對(duì)此規(guī)則或建議給出的反面例子。3 基本原則【原則1-1】首先是為人編寫程序，其次才是計(jì)算機(jī)。說(shuō)明：這是軟件開發(fā)的基本要點(diǎn)，軟件的生命周期貫穿產(chǎn)品的開發(fā)、測(cè)試、生產(chǎn)、用戶使用、版本升級(jí)和后期維護(hù)等長(zhǎng)期過(guò)程，只有易讀、易維護(hù)的軟件代碼才具有生命力?！驹瓌t1-2】保持代碼的簡(jiǎn)明清晰，避免過(guò)分的編程技巧。說(shuō)明：簡(jiǎn)單是最美。保持代碼的簡(jiǎn)單化是軟件工程化的基本要求。不要過(guò)分追求技巧，否則會(huì)降低程序的可讀性?！驹瓌t1-3】所有的代碼盡量遵循ANSI C標(biāo)準(zhǔn)。說(shuō)明：所有的代碼盡可能遵循ANSI C標(biāo)準(zhǔn)，盡可能不使用ANSI C未定義的或編譯器擴(kuò)展的功能?！驹瓌t1-4】編程時(shí)首先達(dá)到正確性，其次考慮效率。說(shuō)明：編程首先考慮的是滿足正確性、健壯性、可維護(hù)性、可移植性等質(zhì)量因素，最后才考慮程序的效率和資源占用?！驹瓌t1-5】避免或少用全局變量。說(shuō)明：過(guò)多地使用全局變量，會(huì)導(dǎo)致模塊間的緊耦合，違反模塊化的要求。【原則1-6】盡量避免使用GOTO語(yǔ)句?！驹瓌t1-7】盡可能重用、修正老的代碼。說(shuō)明：盡量選擇可借用的代碼，對(duì)其修改優(yōu)化以達(dá)到自身要求。【原則1-8】 盡量減少同樣的錯(cuò)誤出現(xiàn)的次數(shù)。說(shuō)明：事實(shí)上，我們無(wú)法做到完全消除錯(cuò)誤，但通過(guò)不懈的努力，可以減少同樣的錯(cuò)誤出現(xiàn)的次數(shù)。4 布局程序布局的目的是顯示出程序良好的邏輯結(jié)構(gòu)，提高程序的準(zhǔn)確性、連續(xù)性、可讀性、可維護(hù)性。更重要的是，統(tǒng)一的程序布局和編程風(fēng)格，有助于提高整個(gè)項(xiàng)目的開發(fā)質(zhì)量，提高開發(fā)效率，降低開發(fā)成本。同時(shí)，對(duì)于普通程序員來(lái)說(shuō)，養(yǎng)成良好的編程習(xí)慣有助于提高自己的編程水平，提高編程效率。因此，統(tǒng)一的、良好的程序布局和編程風(fēng)格不僅僅是個(gè)人主觀美學(xué)上的或是形式上的問(wèn)題，而且會(huì)涉及到產(chǎn)品質(zhì)量，涉及到個(gè)人編程能力的提高，必須引起大家重視。4.1 文件布局【規(guī)則2-1-1】遵循統(tǒng)一的布局順序來(lái)書寫頭文件。說(shuō)明：以下內(nèi)容如果某些節(jié)不需要，可以忽略。但是其它節(jié)要保持該次序。頭文件布局: 文件頭（參見第三章“注釋”）#ifndef 文件名_H（全大寫）#define 文件名_H其它條件編譯選項(xiàng) #include（依次為標(biāo)準(zhǔn)庫(kù)頭文件、非標(biāo)準(zhǔn)庫(kù)頭文件）常量定義 全局宏 全局?jǐn)?shù)據(jù)類型 類定義模板（template）（包括C+中的類模板和函數(shù)模板）全局函數(shù)原型#endif【規(guī)則2-1-2】遵循統(tǒng)一的布局順序來(lái)書寫實(shí)現(xiàn)文件。說(shuō)明：以下內(nèi)容如果某些節(jié)不需要，可以忽略。但是其它節(jié)要保持該次序。實(shí)現(xiàn)文件布局： 文件頭（參見第三章“注釋”） #include（依次為標(biāo)準(zhǔn)庫(kù)頭文件、非標(biāo)準(zhǔn)庫(kù)頭文件） 常量定義 文件內(nèi)部使用的宏 文件內(nèi)部使用的數(shù)據(jù)類型全局變量本地變量（即靜態(tài)全局變量） 局部函數(shù)原型類的實(shí)現(xiàn) 全局函數(shù)局部函數(shù)【規(guī)則2-1-3】使用注釋塊分離上面定義的節(jié)。正例：/ * * 數(shù)據(jù)類型定義 * * / typedef unsigned char BOOLEAN; /* * 函數(shù)原型 * */ int DoSomething(void);【規(guī)則2-1-4】頭文件必須要避免重復(fù)包含。說(shuō)明：可以通過(guò)宏定義來(lái)避免重復(fù)包含。正例：#ifndef MODULE_H #define MODULE_H 文件體 #endif【規(guī)則2-1-5】包含標(biāo)準(zhǔn)庫(kù)頭文件用尖括號(hào) ，包含非標(biāo)準(zhǔn)庫(kù)頭文件用雙引號(hào) “ ”。正例：#include #include “heads.h”【規(guī)則2-1-6】遵循統(tǒng)一的順序書寫類的定義及實(shí)現(xiàn)。說(shuō)明：類的定義（在定義文件中）按如下順序書寫： 公有屬性 公有函數(shù) 保護(hù)屬性 保護(hù)函數(shù) 私有屬性 私有函數(shù)類的實(shí)現(xiàn)（在實(shí)現(xiàn)文件中）按如下順序書寫： 構(gòu)造函數(shù)析構(gòu)函數(shù)公有函數(shù)保護(hù)函數(shù)私有函數(shù)4.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í)行語(yǔ)句有多少都要加 。說(shuō)明：這樣可以防止書寫失誤，也易于閱讀。正例：if (varible1 varible2) varible1 = varible2;反例：下面的代碼執(zhí)行語(yǔ)句緊跟if的條件之后，而且沒(méi)有加，違反規(guī)則。if (varible1 ”這類操作符前后不加空格。正例：!bValueiValue*strSource&fSumaiNumberi = 5;tBox.dWidth tBox-dWidth 【規(guī)則2-4-3】關(guān)鍵字之后要留空格。說(shuō)明：if、for、while等關(guān)鍵字之后應(yīng)留一個(gè)空格再跟左括號(hào)(，以突出關(guān)鍵字?！疽?guī)則2-4-4】函數(shù)名之后不要留空格。說(shuō)明：函數(shù)名后緊跟左括號(hào)(，以與關(guān)鍵字區(qū)別?！疽?guī)則2-4-5】(向后緊跟，)、,、;向前緊跟，緊跟處不留空格。,之后要留空格。;不是行結(jié)束符號(hào)時(shí)其后要留空格。正例：例子中的 凵 代表空格。 for凵(i凵=凵0;凵i凵凵MAX_BSC_NUM;凵i+)DoSomething(iWidth,凵iHeight);【規(guī)則2-4-6】注釋符與注釋內(nèi)容之間要用一個(gè)空格進(jìn)行分隔。正例：/* 注釋內(nèi)容 */ 注釋內(nèi)容反例： /*注釋內(nèi)容*/注釋內(nèi)容4.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 (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);/ 賦值語(yǔ)句的續(xù)行應(yīng)在賦值號(hào)處對(duì)齊fTotalBill = fTotalBill + faCustomerPurchasesiID+ fSalesTax(faCustomerPurchasesiID);【規(guī)則2-5-2】函數(shù)聲明時(shí)，類型與名稱不允許分行書寫。正例：extern double FAR CalcArea(double dWidth, double dHeight);反例：extern double FAR CalcArea(double dWidth, double dHeight);5 注 釋注釋有助于理解代碼，有效的注釋是指在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息，而不是代碼表面意義的簡(jiǎn)單重復(fù)。【規(guī)則3-1】C語(yǔ)言的注釋符為“/* */”。C+語(yǔ)言中，多行注釋采用“/* */”，單行注釋采用“/ ”?！疽?guī)則3-2】一般情況下，源程序有效注釋量必須在20以上。說(shuō)明：注釋的原則是有助于對(duì)程序的閱讀理解，注釋不宜太多也不能太少，注釋語(yǔ)言必須準(zhǔn)確、易懂、簡(jiǎn)潔。有效的注釋是指在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息?！疽?guī)則3-3】注釋使用中文。說(shuō)明：對(duì)于特殊要求的可以使用英文注釋，如工具不支持中文或國(guó)際化版本時(shí)。【規(guī)則3-4】文件頭部必須進(jìn)行注釋，包括：.h文件、.c文件、.cpp文件、.inc文件、.def文件、編譯說(shuō)明文件.cfg等。說(shuō)明：注釋必須列出：版權(quán)信息、文件標(biāo)識(shí)、內(nèi)容摘要、版本號(hào)、作者、完成日期、修改信息等。正例：下面是文件頭部的中文注釋：/* * 文件名稱： / 文件名* 內(nèi)容摘要： / 簡(jiǎn)要描述本文件的內(nèi)容，包括主要模塊、函數(shù)及其功能的說(shuō)明* 其它說(shuō)明： / 其它內(nèi)容的說(shuō)明* 當(dāng)前版本： / 輸入當(dāng)前版本* 作 者： / 輸入作者名字* 完成日期： / 輸入完成日期，例：2004年1月1日* * 修改記錄1：/ 修改歷史記錄，包括修改日期、修改者及修改內(nèi)容* 修改日期：* 版 本 號(hào)：* 修 改 人：* 修改內(nèi)容： * 修改記錄2：*/【規(guī)則3-5】函數(shù)頭部應(yīng)進(jìn)行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、修改信息等。說(shuō)明：注釋必須列出：函數(shù)名稱、功能描述、輸入?yún)?shù)、輸出參數(shù)、返 回 值、修改信息等。正例：下面是函數(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)容* -* 2004/01/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ǔ)句結(jié)束 /* end of if () */ / 指明是哪條語(yǔ)句結(jié)束 /* end of void main（）*/ / 指明函數(shù)的結(jié)束【規(guī)則3-7】保證代碼和注釋的一致性。修改代碼同時(shí)修改相應(yīng)的注釋，不再有用的注釋要?jiǎng)h除?！疽?guī)則3-8】注釋應(yīng)與其描述的代碼相近，對(duì)代碼的注釋應(yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。說(shuō)明：在使用縮寫時(shí)或之前，應(yīng)對(duì)縮寫進(jìn)行必要的說(shuō)明。正例： 如下書寫比較結(jié)構(gòu)清晰/* 獲得子系統(tǒng)索引 */iSubSysIndex = aDataiIndex.iSysIndex;/* 代碼段1注釋 */ 代碼段1 /* 代碼段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)碼）* 變量范圍：例如0 - SUCCESS 1 - Table error * 訪問(wèn)說(shuō)明：（訪問(wèn)的函數(shù)以及方法）*/BYTE g_ucTranErrorCode; 【規(guī)則3-10】注釋與所描述內(nèi)容進(jìn)行同樣的縮排。說(shuō)明：可使程序排版整齊，并方便注釋的閱讀與理解。正例： 如下注釋結(jié)構(gòu)比較清晰int DoSomething(void)/* 代碼段1注釋 */ 代碼段1 /* 代碼段2注釋 */ 代碼段2 反例：如下例子，排版不整齊，閱讀不方便；int DoSomething(void)/* 代碼段1注釋 */ 代碼段1 /* 代碼段2注釋 */ 代碼段2 【規(guī)則3-11】對(duì)分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）必須編寫注釋。說(shuō)明：這些語(yǔ)句往往是程序?qū)崿F(xiàn)某一特殊功能的關(guān)鍵，良好的注釋有助于更好的理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。建議3-1通過(guò)對(duì)函數(shù)或過(guò)程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼結(jié)構(gòu)，使代碼成為自注釋的。說(shuō)明：清晰準(zhǔn)確的函數(shù)、變量命名，可增加代碼的可讀性，減少不必要的注釋。建議3-2盡量避免在注釋中使用縮寫，特別是不常用縮寫。說(shuō)明：在使用縮寫時(shí)，應(yīng)對(duì)縮寫進(jìn)行必要的說(shuō)明。6 命名規(guī)則好的命名規(guī)則能極大地增加可讀性和可維護(hù)性。同時(shí)，對(duì)于一個(gè)有多個(gè)人共同完成的大項(xiàng)目來(lái)說(shuō)，統(tǒng)一命名約定也是一項(xiàng)必不可少的內(nèi)容。本章對(duì)程序中的所有標(biāo)識(shí)符（包括變量名、常量名、函數(shù)名、類名、結(jié)構(gòu)名、宏定義等）的命名做出約定?！疽?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-2】標(biāo)識(shí)符只能由26個(gè)英文字母，10個(gè)數(shù)字，及下劃線的一個(gè)子集來(lái)組成，并嚴(yán)格禁止使用連續(xù)的下劃線，下劃線也不能出現(xiàn)在標(biāo)識(shí)符頭或結(jié)尾（預(yù)編譯開關(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ò)去掉“元音”形成縮寫，較長(zhǎng)的單詞可取單詞的頭幾個(gè)字母形成縮寫，一些單詞有大家公認(rèn)的縮寫，常用單詞的縮寫必須統(tǒng)一。協(xié)議中的單詞的縮寫與協(xié)議保持一致。對(duì)于某個(gè)系統(tǒng)使用的專用縮寫應(yīng)該在某處做統(tǒng)一說(shuō)明。正例：如下單詞的縮寫能夠被大家認(rèn)可： temp 可縮寫為 tmp ； flag 可縮寫為 flg ； statistic 可縮寫為 stat ； increment 可縮寫為 inc ； message 可縮寫為 msg ；規(guī)定的常用縮寫如下： 常用詞縮寫ArgumentArgBufferBufClearClrClockClkCompareCmpConfigurationCfgContextCtxDelayDlyDeviceDevDisableDisDisplayDispEnableEnErrorErrFunctionFnctHexadecimalHexHigh Priority TaskHPTI/O SystemIOSInitializeInitMailboxMboxManagerMgrMaximumMaxMessageMsgMinimumMinMultiplexMuxOperating SystemOSOverflowOvfParameterParamPointerPtrPreviousPrevPriorityPrioReadRdReadyRdyRegisterRegScheduleSchedSemaphoreSemStackStkSynchronizeSyncTimerTmrTriggerTrigWriteWr【規(guī)則4-4】程序中不要出現(xiàn)僅靠大小寫區(qū)分的相似的標(biāo)識(shí)符?！疽?guī)則4-5】用正確的反義詞組命名具有互斥意義的變量或相反動(dòng)作的函數(shù)等。說(shuō)明：下面是一些在軟件中常用的反義詞組。 add/remove ； begin/end ； create/destroy ； insert/delete ； first/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】宏、常量名都要使用大寫字母, 用下劃線 _ 分割單詞。預(yù)編譯開關(guān)的定義使用下劃線 _ 開始。正例：如 DISP_BUF_SIZE、MIN_VALUE、MAX_VALUE 等等?！疽?guī)則4-7】變量名長(zhǎng)度應(yīng)小于31個(gè)字符，以保持與ANSI C標(biāo)準(zhǔn)一致。不得取單個(gè)字符（如i、j、k等）作為變量名，但是局部循環(huán)變量除外。說(shuō)明：變量，尤其是局部變量，如果用單個(gè)字符表示，很容易出錯(cuò)（如l誤寫成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ū)分變量的作用域。說(shuō)明：變量活動(dòng)范圍前綴規(guī)范如下： g_ ： 全局變量 s_ ： 模塊內(nèi)靜態(tài)變量 空 ： 局部變量不加范圍前綴【規(guī)則4-10】使用一致的小寫類型指示符作