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

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