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 內(nèi)聯(lián) 144.12 靜態(tài)變量 144.13 編譯依賴 154.14 可重入 155 內(nèi)存管理規(guī)則 165.1 模塊化 165.2 靜態(tài)分派 165.3 new/delete 165.4 有效性 165.5 對的釋放 165.6 拷貝 166 注釋規(guī)則 176.1 有效性 176.2 普通注釋 176.3 Doxygen注釋 176.4 定義 176.5 申明 186.6 模塊 187 維護規(guī)則 197.1 消除警告 197.2 代碼修改 197.3 標本兼治 19參考資料 20

重要提醒 本規(guī)范中的示例代碼都在表格框中顯示，綠色的表格框表達對的的示例代碼，紅色的表格框表達不建議的示例代碼。背景 C++是大華設(shè)備軟件和平臺軟件開發(fā)的重要軟件，在新的軟件框架里，兩種平臺的組件甚至是共用的。統(tǒng)一的代碼風(fēng)格，良好的設(shè)計風(fēng)格，有助于代碼的實現(xiàn)和閱讀，有助于減少代碼錯誤和提高代碼效率，能有效地促進技術(shù)的交流和發(fā)展。 常見的代碼規(guī)范都異常冗長，調(diào)調(diào)框框太多。本規(guī)范力求以簡明的內(nèi)容，概括一些重要的規(guī)則，將相似的規(guī)則進行提煉集中描述，并提供對照的示例代碼加深理解。規(guī)范的使用者花半個小時左右，就可以熟悉整個規(guī)范。 所有大華基于新軟件框架的底層組件，業(yè)務(wù)組件，應(yīng)用組件都必須遵守此規(guī)范。例外 本規(guī)范是強制規(guī)定，但是有些情況例外：與第三方庫有關(guān)的代碼：比如stl,boost,json等等，使用、移植這些庫時，相關(guān)的代碼可以按照這些庫的規(guī)范。Windows代碼：重要指基于公共軟件框架，同時使用了非公共組件框架內(nèi)的其他API接口的組件，可以繼續(xù)保存Windows的規(guī)范。文獻組織規(guī)則命名所有的目錄和文獻名使用大寫字母開頭的單詞組合，目錄名單詞之間可以用空格分開。引用文獻名時要嚴格區(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源文獻，內(nèi)部頭文獻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)進行注釋，列出svn文獻ID，版權(quán)申明，文獻描述(說明是什么模塊或什么類相應(yīng)的文獻)，修改記錄(修改時間、svn作者、修改內(nèi)容)，可使用va模板。對于新加入svn的文獻，應(yīng)當(dāng)其文獻屬性的svn屬性列表中加入(svn:keywords,Id)屬性。不要和文獻中的類或模塊的注釋混淆。////"$Id$“////Copyright(c)1992-2023,ZheJiangDahuaTechnologyStockCO.LTD.//AllRightsReserved.//// Description:// Revisions: Year-Month-DaySVN-AuthorModification//代碼組織規(guī)則空行類、結(jié)構(gòu)、聯(lián)合、函數(shù)、枚舉等定義結(jié)束后，應(yīng)加空行。類定義內(nèi)部相關(guān)的成員變量或操作之間不加空行，其他地方應(yīng)加空行。函數(shù)體內(nèi)，邏揖上密切相關(guān)的語句之間不加空行，其它地方應(yīng)加空行。源文獻和頭文獻末尾保存一個空行。classA{};classB;換行每行代碼只寫一條語句。拆分復(fù)雜的復(fù)合表達式。代碼行長度控制在80左右。長表達式在低優(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)獨占一行并且位于同一列，同時與引用它們的語句左對齊。{}之內(nèi)的代碼塊使用TAB縮進并對齊，換行后的代碼塊使用TAB縮進并對齊。代碼前的注釋應(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)在類定義中對該類型進行更簡潔自定義。訪問一個變量的表達式太長，應(yīng)定義一個臨時的指針或引用來替換它。函數(shù)中多次調(diào)用返回結(jié)果不變的其他函數(shù)，應(yīng)使用臨時變量保存結(jié)果。函數(shù)中多次引用單件，應(yīng)使用臨時變量甚至類的成員變量來保存單件的引用或指針。將if/else/return的組合改為return條件表達式組合。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ī)則，提高拼寫效率。自注釋標記符應(yīng)是故意義的單詞或其組合。用約定俗成的詞，除了通用的縮寫，應(yīng)使用全拼。拼寫要對的，注意單復(fù)數(shù)，嚴禁使用拼音。用最短的長度表達最準確的信息。//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)當(dāng)是是小寫的模塊名。類的成員函數(shù)應(yīng)當(dāng)只使用“動詞”，被省略掉的名詞就是對象自身。voidsleep(); //全局函int setValue(…); //全局函數(shù)int getValue(…); //全局函數(shù)voidglCallList(GLuintlist);//OpenGLAPIbox->draw(); //成員函數(shù)類型可直接使用bool，char等內(nèi)建類型，其他使用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ù)基本原則是高抽象性，高內(nèi)聚性，低耦合性。使類的接口完整并且最小。一個函數(shù)不要完畢多個功能。一個變量也不能有多用途。把方法中的反復(fù)代碼抽象成私有函數(shù)。盡量使用已有的函數(shù)或者標準庫來實現(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ù)對成員進行初始化。假如擬定只有一個構(gòu)造函數(shù)，應(yīng)使用成員初始化列表進行初始化。并且初始化列表中成員列出的順序和它們在類中聲明的順序相同。使用explicit關(guān)鍵字消除隱式轉(zhuǎn)換classCString{ //… explicitCString(intn);//preallocatenbytes CString(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)當(dāng)加const修飾，妥善解決const的傳遞性。將只與類有關(guān)的常量、類型的定義放在類的內(nèi)部。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)當(dā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ù)進入和退出時檢查不變式。對于運營契約檢查，一般使用assert，也可以采用日記記錄，拋出異常等方式。///獲取隊首元素constT&front(){ assert(m_size>0); returnm_queue[m_front];}不要混淆運營契約與有效代碼，運營契約僅檢查參數(shù)的合法性，且不應(yīng)修改契約外定義的變量。assert(--m_count>0);規(guī)模函數(shù)參數(shù)個數(shù)盡量控制在5個之內(nèi)。函數(shù)代碼盡量控制在200行代碼之內(nèi)。每個類的平均方法數(shù)盡量控制在20個之內(nèi)。函數(shù)嵌套深度控制在6級之內(nèi)，減少沒必要的遞歸嵌套。函數(shù)（調(diào)度函數(shù)除外）扇出控制在5個以內(nèi)。類型轉(zhuǎn)換避免強制類型轉(zhuǎn)換。避免隱藏類型轉(zhuǎn)換。常量C++中使用const來定義常量，替換宏定義的常量。不能使用無意義的立即數(shù)。類中使用的常量應(yīng)使用類的內(nèi)部定義的枚舉類型的值。只能使用ascii字符的字符串常量，不能使用中文等特定語言的字符串常量。內(nèi)聯(lián)C++中應(yīng)當(dāng)用內(nèi)聯(lián)函數(shù)替換宏定義的代碼段。對性能規(guī)定比較高的場合應(yīng)使用內(nèi)聯(lián)函數(shù)。使用C++標準庫常用的內(nèi)聯(lián)函數(shù)，比如max，min等。假如使用某函數(shù)的地方較多，并且函數(shù)體較大，不應(yīng)使用內(nèi)聯(lián)函數(shù)。解耦合解耦合設(shè)計到很多方面，涉及模塊的劃分，頭文獻依賴，模塊對外的接口必須有解耦合解決，隱藏內(nèi)部實現(xiàn)的細節(jié)，避免編譯依賴。假如可以使用對象的引用和指針，就要避免使用對象自身。定義某個類型的引用和指針只會涉及到這個類型的聲明。定義此類型的對象則需要類型定義的參與。盡也許使用類的聲明，而不使用類的定義。由于在聲明一個函數(shù)時，假如用到某個類，是絕對不需要這個類的定義的，即使函數(shù)是通過傳值來傳遞和返回這個類。不要在頭文獻中再包含其它頭文獻，除非缺少了它們就不能編譯。相反，要一個一個地聲明所需要的類，讓使用這個頭文獻的用戶自己去包含其它的頭文獻，以使用戶代碼最終得以通過編譯。使用句柄類(Handleclass)隱藏實現(xiàn)細節(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ù)訪問的資源，要使用互斥量保護，上層應(yīng)用不應(yīng)直接使用中斷。保護的范圍要準確，一般使用不同的互斥量來保護不同的資源，假如整體的代價不高，也可以使用同一個互斥量。仔細考察資源之間依賴的情況，防止死鎖。使用Guard（守衛(wèi)者）來實現(xiàn)函數(shù)內(nèi)的保護，除非難以使用。通過邏輯的設(shè)計，可以保證多個線程訪問同一資源不會發(fā)生沖突時，可以不保護。對于只需要自加和自減的變量可以使用AtomicCount來保證原子性。

內(nèi)存管理規(guī)則模塊化使用或者設(shè)計專有的內(nèi)存管理模塊，而不是直接使用new/delete。給標準容器編寫高效安全的allocator。使用智能指針管理內(nèi)存或?qū)ο笊芷?。靜態(tài)分派在程序啟動時從系統(tǒng)中靜態(tài)分派好需要連續(xù)使用的內(nèi)存，提高性能。new/deleteC++中使用new/delete替換malloc/free。假如重載了operatornew就要同時重載operatordelete。有效性使用有效的指針及其所指向的空間，杜絕野指針。對的釋放明確內(nèi)存塊的所屬對象及對象的生命周期，及時釋放，防止內(nèi)存泄露。new出來的數(shù)組釋放時也應(yīng)表白它是數(shù)組?？截悢?shù)組拷貝，或調(diào)用內(nèi)存拷貝、字符串拷貝接口時，應(yīng)注意源區(qū)域和目的區(qū)域重疊的情況，參考memmove函數(shù)。

注釋規(guī)則有效性注釋的內(nèi)容要清楚、明了，含義準確，防止注釋二義性。在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。對于已經(jīng)充足自注釋限度的代碼無需注釋。普通注釋函數(shù)內(nèi)部使用C++注釋風(fēng)格，并在注釋符號和注釋內(nèi)容間留一個空格。注釋內(nèi)容加在代碼對象的上方或右方。if、for、do、while、case、switch、default等語句應(yīng)當(dāng)注釋。未break的case段后面應(yīng)當(dāng)注釋。代碼塊、預(yù)解決塊較長的，應(yīng)當(dāng)注釋。Doxygen注釋函數(shù)外部使用DoxygenC++風(fēng)格注釋，并在注釋符號和注釋內(nèi)容間留一個空格。注釋由簡要注釋和具體注釋組成，兩者都是可選的，且是兩者都不能反復(fù)。簡要注釋使用一行C++注釋，并在開始加一個額外的斜杠，使用\brief命令可以支持多行，簡要注釋的范圍將以空行或其他命令結(jié)束。具體注釋使用至少兩行C++注釋，每行開始加一個額外的斜杠。注釋塊可以加在代碼對象的上面或者右方，假如加在右方，還需要加額外的<符號，只有成員和參數(shù)的注釋可以加在右邊。一般使用簡要注釋即可，如需要更具體的說明的可以使用具體注釋，具體注釋應(yīng)和其他注釋用空行隔開。///Briefdescription.//////Detaileddescription.///somecodeitemheresomecodeitemhere///<Briefdescription. 定義對于類，結(jié)構(gòu)，聯(lián)合，枚舉，函數(shù)，宏，自定義類型，名字空間，非局部變量等定義均需要使用Doxygen簡要注釋。對于類，結(jié)構(gòu)，聯(lián)合，枚舉等成員使用右置的D