./C++設(shè)計編碼規(guī)V1.00〔試用版設(shè)備開發(fā)部黃煥斌目錄重要提示4背景41文件組織規(guī)則41.1命名41.2目錄41.3預(yù)處理41.4注釋52代碼組織規(guī)則62.1空行62.2換行62.3空格62.4對齊72.5就近原則72.6精簡原則73命名規(guī)則93.1自注釋93.2變量93.3函數(shù)93.4類型103.5宏103.6常量104設(shè)計規(guī)則114.1識別類和函數(shù)114.2構(gòu)造函數(shù)114.3封裝性124.4函數(shù)參數(shù)124.5函數(shù)返回值134.6契約134.7規(guī)模144.8名字空間144.9類型轉(zhuǎn)換144.10常量144.11聯(lián)144.12靜態(tài)變量144.13編譯依賴154.14可重入155存管理規(guī)則165.1模塊化165.2靜態(tài)分配165.3new/delete165.4有效性165.5正確釋放165.6拷貝166注釋規(guī)則176.1有效性176.2普通注釋176.3Doxygen注釋176.4定義176.5申明186.6模塊187維護(hù)規(guī)則197.1消除警告197.2代碼修改197.3標(biāo)本兼治19參考資料20重要提示 本規(guī)中的示例代碼都在表格框中顯示,綠色的表格框表示正確的示例代碼,紅色的表格框表示不建議的示例代碼。背景 C++是大華設(shè)備軟件和平臺軟件開發(fā)的主要軟件,在新的軟件框架里,兩種平臺的組件甚至是共用的。統(tǒng)一的代碼風(fēng)格,良好的設(shè)計風(fēng)格,有利于代碼的實現(xiàn)和閱讀,有利于減少代碼錯誤和提高代碼效率,能有效地促進(jìn)技術(shù)的交流和發(fā)展。 常見的代碼規(guī)都異常冗長,調(diào)調(diào)框框太多。本規(guī)力求以簡明的容,概括一些重要的規(guī)則,將相似的規(guī)則進(jìn)行提煉集中描述,并提供對照的示例代碼加深理解。規(guī)的使用者花半個小時左右,就可以熟悉整個規(guī)。 所有大華基于新軟件框架的底層組件,業(yè)務(wù)組件,應(yīng)用組件都必須遵守此規(guī)。例外 本規(guī)是強(qiáng)制要求,不過有些情況例外：與第三方庫有關(guān)的代碼：比如stl,boost,json等等,使用、移植這些庫時,相關(guān)的代碼可以按照這些庫的規(guī)。Windows代碼：主要指基于公共軟件框架,同時使用了非公共組件框架的其他API接口的組件,可以繼續(xù)保留Windows的規(guī)。文件組織規(guī)則命名所有的目錄和文件名使用大寫字母開頭的單詞組合,目錄詞之間可以用空格分開。引用文件名時要嚴(yán)格區(qū)分大小寫。與操作系統(tǒng)關(guān)系密切的工程的命名可以參考操作系統(tǒng)的規(guī)則。Timer.cpp //源文件Timer.h //頭文件Font.bin //資源文件Config1 //配置文件目錄一個大的工程是由多個組件或模塊組成的,對于每個組件或模塊,其代碼應(yīng)集中管理,并具備完整的設(shè)計文檔和單元測試代碼,用子目錄分類存放。目錄或文件說明Bin測試程序目錄Doc設(shè)計文檔目錄Include依賴的組件頭文件目錄與本組件的外部接口頭文件目錄,映射到其他地址Lib不同平臺生成的庫和依賴的庫文件目錄Makefile.ConfigsMakefile的不同平臺的配置文件目錄Src源文件,部頭文件Test單元測試代碼MakefileallRules.mkMakefile文件,一次性編譯Makefile.Configs目錄下所有配置對應(yīng)的庫,測試程序預(yù)處理為了防止頭文件被重復(fù)引用,使用ifndef/define/endif結(jié)構(gòu)產(chǎn)生預(yù)處理塊。預(yù)處理宏中的單詞應(yīng)與文件名基本一致。//文件名為Guard.h#ifndef__GUARD_H__#define__GUARD_H__//Guard類的定義...#endif//__GUARD_H__注釋源文件和頭文件的頭部都應(yīng)進(jìn)行注釋,列出svn文件ID,申明,文件描述<說明是什么模塊或什么類對應(yīng)的文件>,修改記錄<修改時間、svn作者、修改容>,可使用va模板。對于新加入svn的文件,應(yīng)該其文件屬性的svn屬性列表中加入<svn:keywords,Id>屬性。不要和文件中的類或模塊的注釋混淆。////"$Id$"http:////Copyright<c>1992-2007,ZheJiangDahuaTechnologyStockCO.LTD.//AllRightsReserved.//// Description:// Revisions: Year-Month-DaySVN-AuthorModification//代碼組織規(guī)則空行類、結(jié)構(gòu)、聯(lián)合、函數(shù)、枚舉等定義結(jié)束后,應(yīng)加空行。類定義部相關(guān)的成員變量或操作之間不加空行,其他地方應(yīng)加空行。函數(shù)體,邏揖上密切相關(guān)的語句之間不加空行,其它地方應(yīng)加空行。源文件和頭文件末尾保留一個空行。classA{};classB;換行每行代碼只寫一條語句。拆分復(fù)雜的復(fù)合表達(dá)式。代碼行長度控制在80左右。長表達(dá)式在低優(yōu)先級操作符處拆分成新行,操作符放在新行之首。if<loadFile<m_customFilePath.c_str<>,m_stream> &&reader.parse<m_stream,m_configAll> &&m_configAll["Groups"].size<>>=1 &&m_configAll["Users"].size<>>=1>{ infof<"CUserManager::SetDefault<>applycustomconfig.\n">;}空格‘,’之后要留空格。如果‘;’不是一行的結(jié)束符號,其后要留空格。二目或三目操作符前后留空格。但"［］"、"."、"->"這類操作符和作用于分辨符"::"前后不加空格。修飾符‘*’和‘＆’緊靠變量名,僅在前面加空格。char*name;int*x,y; //此處y不會被誤解為指針for<inti=0;i<N;i++>{}對齊程序的分界符‘{’和‘}’應(yīng)獨占一行并且位于同一列,同時與引用它們的語句左對齊。{}之的代碼塊使用TAB縮進(jìn)并對齊,換行后的代碼塊使用TAB縮進(jìn)并對齊。代碼前的注釋應(yīng)和所注釋的代碼對齊。//commentoffoovoidfoo<>{ dosomething}就近原則較為緊密的代碼應(yīng)盡可能相鄰。變量應(yīng)在在定義的同時初始化。C++函數(shù)中將局部變量的定義放在要使用它的代碼前最近處。將類的public接口申明放在類定義的最前面。voidfoo<>{ inta=0; a++; … intb=0; b++; …}精簡原則DRY<Don'tRepeatYourself>系統(tǒng)中的每一項知識都需具有單一的表示。KISS<KeepItSimpleStupid>保持盡量簡單。類中多次使用定義的很長的類型,應(yīng)在類定義中對該類型進(jìn)行更簡潔自定義。訪問一個變量的表達(dá)式太長,應(yīng)定義一個臨時的指針或引用來替換它。函數(shù)中多次調(diào)用返回結(jié)果不變的其他函數(shù),應(yīng)使用臨時變量保存結(jié)果。函數(shù)中多次引用單件,應(yīng)使用臨時變量甚至類的成員變量來保存單件的引用或指針。將if/else/return的組合改為return條件表達(dá)式組合。Json::Value&users=m_configAll["Users"];for<uinti=pos;i<users.size<>-1;i++>{ users[i]=users[i+1];}users.resize<users.size<>-1>;return<condition?x:y>;命名規(guī)則整體上采用Java的命名規(guī)則,提高拼寫效率。自注釋標(biāo)識符應(yīng)是有意義的單詞或其組合。用約定俗成的詞,除了通用的縮寫,應(yīng)使用全拼。拼寫要正確,注意單復(fù)數(shù),禁止使用拼音。用最短的長度表達(dá)最準(zhǔn)確的信息。//smellyexampletypedefstructtagPICINFO_INJPG

{

char

jpglog[4];

//

int

type;

//類型0:通行1:超速<暫無效>

char

sbid[10];

//設(shè)備ID

int

xscd;

//形行駛ID

char

cphm[20];

//車牌

int

cplx;

//車牌類型

int

cpys;

//車牌顏色

char

tgsj[19];

//抓拍時間…

}PICINFO_INJPG;變量使用"名詞"或者"形容詞＋名詞",首個單詞首字母小寫開頭,其他單詞大寫打頭。全局變量加前綴"g_"。成員變量加前綴"m_",結(jié)構(gòu)和聯(lián)合的成員變量不用加。靜態(tài)變量加前綴"s_",靜態(tài)成員變量加"sm_"。floatvalue;floatoldValue;floatnewValue;函數(shù)使用"動詞"或者"動詞＋名詞"〔動賓詞組,名詞前可再加修飾詞,首個單詞首字母小寫開頭,其他單詞大寫打頭。C-API函數(shù)最前面應(yīng)該是是小寫的模塊名。類的成員函數(shù)應(yīng)當(dāng)只使用"動詞",被省略掉的名詞就是對象本身。voidsleep<>; //全局函int setValue<…>; //全局函數(shù)int getValue<…>; //全局函數(shù)voidglCallList<GLuintlist>;//OpenGLAPIbox->draw<>; //成員函數(shù)類型可直接使用bool,char等建類型,其他使用stdint.h定義的類型。算術(shù)自定義類型,類,結(jié)構(gòu),聯(lián)合,枚舉類型統(tǒng)一使用大寫字母開頭的單詞組合。class類型的命名前加大寫字母’C’；templateclass類型的命名前加大寫字母’T’；接口類的命名前加大寫字母’I’。在類中嵌套的定義有具體意義的類型,是代碼更易讀。typedefintDistance;unionAddress;enumMode;structUser;classCPacket;template<classT,classA=std::allocator<T>> classTCircularQueue;classIDevVideoEnc;宏全部使用大寫字母,單詞之間用下劃線分開。給代碼控制宏命名加上前綴,來分類不同用途的宏。以上都是指自定義的宏,不包括編譯預(yù)定義宏。#defineJSON_VALUE_USE_INTERNAL_MAP1#defineJSON_USE_CPPTL1常量避免使用常量宏,不得不使用時,參考宏的命名規(guī)則。const,枚舉值等常量,應(yīng)盡量作為類的成員,命名方式和變量相同。#defineMAX_SIZE10//notsogoodclassA{ enum { maxSize=10 };}設(shè)計規(guī)則識別類和函數(shù)基本原則是高抽象性,高聚性,低耦合性。使類的接口完整并且最小。一個函數(shù)不要完成多個功能。一個變量也不能有多用途。把方法中的重復(fù)代碼抽象成私有函數(shù)。盡量使用已有的函數(shù)或者標(biāo)準(zhǔn)庫來實現(xiàn)新的函數(shù)。區(qū)分兩個類"A是一個B"與"A是B的一部分"的關(guān)系,分別對應(yīng)類的繼承和聚合關(guān)系。//正確的設(shè)計,雖然代碼冗長。

classHead

{

public:

voidLook<void>{m_eye.Look<>;}

voidSmell<void>{m_nose.Smell<>;}

voidEat<void>{m_mouth.Eat<>;}

voidListen<void>{m_ear.Listen<>;}

private:

Eyem_eye;

Nosem_nose;

Mouthm_mouth;

Earm_ear;

};如果允許Head從Eye、Nose、Mouth、Ear派生而成,那么Head將自動具有Look、Smell、Eat、Listen這些功能。示例十分簡短并且運行正確,但是這種設(shè)計方法卻是不對的。//功能正確并且代碼簡潔,但是設(shè)計方法不對。classHead:publicEye,publicNose,publicMouth,publicEar{};構(gòu)造函數(shù)如果一個類可能有多個構(gòu)造函數(shù),應(yīng)有公用的私有初始化函數(shù)對成員進(jìn)行初始化。如果確定只有一個構(gòu)造函數(shù),應(yīng)使用成員初始化列表進(jìn)行初始化。并且初始化列表中成員列出的順序和它們在類中聲明的順序相同。使用explicit關(guān)鍵字消除隱式轉(zhuǎn)換classCString{//…explicitCString<intn>;//preallocatenbytesCString<constchar*p>;};CStrings1=‘a(chǎn)’;//error:noimplicitchar->CStringconversionCStrings2<10>;//ok:stringwithspacefor10characters將采用了單件實例的類或接口的構(gòu)造函數(shù)和析構(gòu)函數(shù)權(quán)限設(shè)置為private或protectedclassITimerManager{public: staticITimerManager*instance<>;protected: ITimerManager<>; virtual~ITimerManager<>;…析構(gòu)函數(shù)確定基類有虛析構(gòu)函數(shù)?？截惡瘮?shù)與賦值函數(shù)為非POD類型〔plain-old-data,onlyints,chars,floats,orpointers,orarrays/structsofPOD類聲明一個拷貝構(gòu)造函數(shù)和一個賦值操作符。而且在operator=中,應(yīng)返回*this的引用,對所有數(shù)據(jù)成員賦值,檢查給自己賦值的情況。classCZString{public: CZString<constchar*cstr>; CZString<constCZString&other>; ~CZString<>; CZString&operator=<constCZString&other> { if<this==&other>return*this; CZStringtemp<other>; constchar*cstr=m_cstr; m_cstr=temp.m_cstr; temp.m_cstr=cstr; }private: constchar*m_cstr;}封裝性不要重新定義繼承而來的非虛函數(shù)、成員、函數(shù)的缺省參數(shù)值。避免出現(xiàn)public數(shù)據(jù)成員。單件模式對象構(gòu)造函數(shù)應(yīng)為私有類型。如果一個操作不會修改對象的屬性,應(yīng)該加const修飾,妥善處理const的傳遞性。將只與類有關(guān)的常量、類型的定義放在類的部。classA{public: intgetValue<>const;private: intvalue; classInfo { };}函數(shù)參數(shù)如果參數(shù)是一個對象,應(yīng)改成傳遞其引用或者指針。如果參數(shù)是指針或引用,且僅作輸入用,則應(yīng)在類型前加const,注意值傳遞不用修飾。sizt_tstrlen<constchar*string>;CRect<constCPoint&point,constCSize&size>;不能計算指針形參對應(yīng)的實參數(shù)組的大小〔已退化。函數(shù)的參數(shù)順序應(yīng)該是先輸入?yún)?shù),再是輸出參數(shù),同時數(shù)組的地址在前,長度在后。函數(shù)返回值不要返回棧對象的指針或引用,不要返回棧數(shù)組。Object*createObject<>{ Objectobject; return&object;}設(shè)計函數(shù)時,必須返回一個對象時不要試圖返回一個引用。Object&createObject<>{ Objectobject; returnobject;}Object&createObject<>{ Object*object=newObject; return*object;}契約提供約束,寧可編譯和時出錯,也不要運行時出錯。檢查函數(shù)的前置條件,滿足前置條件是調(diào)用者的責(zé)任,而被調(diào)用者假定它的前置條件已經(jīng)滿足。檢查函數(shù)的后置條件,也就是函數(shù)返回之時哪些條件是調(diào)用者可以期望的。檢查類的不變式,類的不變式確保類處于良好的狀態(tài)中,一般提供一個成員函數(shù)如isValid<>在函數(shù)進(jìn)入和退出時檢查不變式。對于運行契約檢查,一般使用assert,也可以采用日志記錄,拋出異常等方式。///獲取隊首元素constT&front<>{ assert<m_size>0>; returnm_queue[m_front];}不要混淆運行契約與有效代碼,運行契約僅檢查參數(shù)的合法性,且不應(yīng)修改契約外定義的變量。assert<--m_count>0>;規(guī)模函數(shù)參數(shù)個數(shù)盡量控制在5個之。函數(shù)代碼盡量控制在200行代碼之。每個類的平均方法數(shù)盡量控制在20個之。函數(shù)嵌套深度控制在6級之,減少沒必要的遞歸嵌套。函數(shù)〔調(diào)度函數(shù)除外扇出控制在5個以。類型轉(zhuǎn)換避免強(qiáng)制類型轉(zhuǎn)換。避免隱藏類型轉(zhuǎn)換。常量C++中使用const來定義常量,替換宏定義的常量。不能使用無意義的立即數(shù)。類中使用的常量應(yīng)使用類的部定義的枚舉類型的值。只能使用ascii字符的字符串常量,不能使用中文等特定語言的字符串常量。聯(lián)C++中應(yīng)該用聯(lián)函數(shù)替換宏定義的代碼段。對性能要求比較高的場合應(yīng)使用聯(lián)函數(shù)。使用C++標(biāo)準(zhǔn)庫常用的聯(lián)函數(shù),比如max,min等。如果使用某函數(shù)的地方較多,而且函數(shù)體較大,不應(yīng)使用聯(lián)函數(shù)。解耦合解耦合設(shè)計到很多方面,包括模塊的劃分,頭文件依賴,模塊對外的接口必須有解耦合處理,隱藏部實現(xiàn)的細(xì)節(jié),避免編譯依賴。如果可以使用對象的引用和指針,就要避免使用對象本身。定義某個類型的引用和指針只會涉及到這個類型的聲明。定義此類型的對象則需要類型定義的參與。盡可能使用類的聲明,而不使用類的定義。因為在聲明一個函數(shù)時,如果用到某個類,是絕對不需要這個類的定義的,即使函數(shù)是通過傳值來傳遞和返回這個類。不要在頭文件中再包含其它頭文件,除非缺少了它們就不能編譯。相反,要一個一個地聲明所需要的類,讓使用這個頭文件的用戶自己去包含其它的頭文件,以使用戶代碼最終得以通過編譯。使用句柄類<Handleclass>隱藏實現(xiàn)細(xì)節(jié)來實現(xiàn)解耦合。//編譯器還是要知道這些類型名,因為Person的構(gòu)造函數(shù)要用到它們classDate;

classAddress;

classPersonImpl;classPerson{

public:

Person<conststring&name,constDate&birthday,constAddress&addr>;

virtual~Person<>;

stringname<>const;

stringbirthDate<>const;

stringaddress<>const;

private:

PersonImpl*impl;

//指向具體的實現(xiàn)類};除了句柄類,另一選擇是使Person成為一種特殊類型的抽象基類,稱為協(xié)議類〔Protocolclass。和句柄類的用戶一樣,協(xié)議類的用戶只是在類的接口被修改的情況下才需要重新編譯。classPerson{

public:

virtual~Person<>;

virtualstringname<>const=0;

virtualstringbirthDate<>const=0;

virtualstringaddress<>const=0;

virtualstringnationality<>const=0;

};可重入對于可能被多個任務(wù)訪問的資源,要使用互斥量保護(hù),上層應(yīng)用不應(yīng)直接使用中斷。保護(hù)的圍要準(zhǔn)確,一般使用不同的互斥量來保護(hù)不同的資源,如果整體的代價不高,也可以使用同一個互斥量。仔細(xì)考察資源之間依賴的情況,防止死鎖。使用Guard〔守衛(wèi)者來實現(xiàn)函數(shù)的保護(hù),除非難以使用。通過邏輯的設(shè)計,能夠保證多個線程訪問同一資源不會發(fā)生沖突時,可以不保護(hù)。對于只需要自加和自減的變量可以使用AtomicCount來保證原子性。存管理規(guī)則模塊化使用或者設(shè)計專有的存管理模塊,而不是直接使用new/delete。給標(biāo)準(zhǔn)容器編寫高效安全的allocator。使用智能指針管理存或?qū)ο笊芷凇ｌo態(tài)分配在程序啟動時從系統(tǒng)中靜態(tài)分配好需要持續(xù)使用的存,提高性能。new/deleteC++中使用new/delete替換malloc/free。如果重載了operatornew就要同時重載operatordelete。有效性使用有效的指針及其所指向的空間,杜絕野指針。正確釋放明確存塊的所屬對象及對象的生命周期,及時釋放,防止存泄露。new出來的數(shù)組釋放時也應(yīng)表明它是數(shù)組?？截悢?shù)組拷貝,或調(diào)用存拷貝、字符串拷貝接口時,應(yīng)注意源區(qū)域和目標(biāo)區(qū)域重疊的情況,參考memmove函數(shù)。注釋規(guī)則有效性注釋的容要清楚、明了,含義準(zhǔn)確,防止注釋二義性。在代碼的功能、意圖層次上進(jìn)行注釋,提供有用、額外的信息。對于已經(jīng)充分自注釋程度的代碼無需注釋。普通注釋函數(shù)部使用C++注釋風(fēng)格,并在注釋符號和注釋容間留一個空格。注釋容加在代碼對象的上方或右方。if、for、do、while、case、switch、default等語句應(yīng)該注釋。未break的case段后面應(yīng)該注釋。代碼塊、預(yù)處理塊較長的,應(yīng)該注釋。Doxygen注釋函數(shù)外部使用DoxygenC++風(fēng)格注釋,并在注釋符號和注釋容間留一個空格。注釋由簡要注釋和詳細(xì)注釋組成,兩者都是可選的,且是兩者都不能重復(fù)。簡要注釋使用一行C++注釋,并在開始加一個額外的斜杠,使用\brief命令可以支持多行,簡要注釋的圍將以空行或其他命令結(jié)束。詳細(xì)注釋使用至少兩行C++注釋,每行開始加一個額外的斜杠。注釋塊可以加在代碼對象的上面或者右方,如果加在右方,還需要加額外的<符號,只有成員和參數(shù)的注釋可以加在右邊。一般使用簡要注釋即可,如需要更詳細(xì)的說明的可以使用詳細(xì)注釋,詳細(xì)注釋應(yīng)和其他注釋用空行隔開。///Briefdescription.//////Detaileddescription.///somecodeitemheresomecodeitemhere///<Briefdescription.定義對于類,結(jié)構(gòu),聯(lián)合,枚舉,函數(shù),宏,自定義類型,名字空間,非局部變量等定義均需要使用Doxygen簡要注釋。對于類,結(jié)構(gòu),聯(lián)合,枚舉等成員使用右置的Doxygen簡要注釋。如果變量是用來作為某種標(biāo)志而不是連續(xù)的數(shù)值,