SN_IP04編碼規(guī)范與范例_C++規(guī)范V1.2

1、C+編碼規(guī)范 Coding ConventionsPC客戶端項目組C+ 編程標準命名和風(fēng)格我們采用微軟.Net Framework命名規(guī)范，和MicroSoft保持一致，便于融合使用微軟的最佳實踐，也便于閱讀。實際上這涉及到兩種命名規(guī)則：Pascal命名規(guī)則和Camel命名規(guī)則，他們出現(xiàn)的場景不同。這兩種規(guī)范都要求變量命名時少用縮略詞和無意義的字母，變量名稱能夠概括代表的功能，可以由多個詞連續(xù)排列構(gòu)成，每個單詞之間稱為邏輯斷點。l Pascal規(guī)范：變量名稱能夠概括功能，由單詞不間斷組合在一起，每個單詞的首字母都大寫，如：MyClassl Camel規(guī)范：變量名稱能夠概括功能，由單詞不間斷組合

2、在一起，變量首字母小寫，其它的每個單詞都大寫，如：myClassl 匈牙利命名規(guī)則：十分必要的情況下，在變量前加上數(shù)據(jù)類型前綴，盡量不要使用匈牙利命名規(guī)則，因為晦澀難懂。我們采用Resharper作為規(guī)范檢查工具目錄PC客戶端項目組1C+ 編程標準命名和風(fēng)格11命名規(guī)則41.1總則41.2類/結(jié)構(gòu)51.3函數(shù)51.4變量61.5常量71.6枚舉、聯(lián)合、typedef71.7宏、枚舉值82文件結(jié)構(gòu)82.1文件頭注釋82.2頭文件92.3實現(xiàn)文件103代碼風(fēng)格與版式113.1語句與代碼行123.2縮進和對齊123.3最大長度133.4長行拆分133.5空格的使用143.6修飾符的位置163.7注釋

3、164注釋分類說明174.1源文件頭部注釋174.2函數(shù)頭部注釋174.3全局變量的注釋18附：QT控件命名規(guī)范20特別說明：211 命名規(guī)則1.1 總則在軟件開發(fā)這一高度抽象而且十分復(fù)雜的活動中，命名規(guī)則的重要性更顯得尤為突出。一套定義良好并且完整的、在整個項目中統(tǒng)一使用的命名規(guī)范將大大提升源代碼的可讀性和軟件的可維護性。在引入細節(jié)之前，先說明一下命名規(guī)范的整體原則：同一性在編寫一個子模塊或派生類的時候，要遵循其基類或整體模塊的命名風(fēng)格，保持命名風(fēng)格在整個模塊中的同一性。標識符組成標識符采用英文單詞或其組合，應(yīng)當(dāng)直觀且可以拼讀，可望文知意，用詞應(yīng)當(dāng)準確。最小化長度 && 最大

4、化信息量原則在保持一個標識符意思明確的同時，應(yīng)當(dāng)盡量縮短其長度。避免過于相似不要出現(xiàn)僅靠大小寫區(qū)分的相似的標識符，例如“i”與“I”，“function”與“Function”等等。避免在不同級別的作用域中重名程序中不要出現(xiàn)名字完全相同的局部變量和全局變量，盡管兩者的作用域不同而不會發(fā)生語法錯誤，但容易使人誤解。正確命名具有互斥意義的標識符用正確的反義詞組命名具有互斥意義的標識符，如："nMinValue"和"nMaxValue"，"GetName()" 和 "SetName()" .避免名字中出現(xiàn)數(shù)字編號盡量避免

5、名字中出現(xiàn)數(shù)字編號，如Value1,Value2等，除非邏輯上的確需要編號。這是為了防止程序員偷懶，不肯為命名動腦筋而導(dǎo)致產(chǎn)生無意義的名字（因為用數(shù)字編號最省事）。1.2 類/結(jié)構(gòu)除了異常類等個別情況（不希望用戶把該類看作一個普通的、正常的類之情況）外，C+類/結(jié)構(gòu)的命名應(yīng)該遵循以下準則：C+類/結(jié)構(gòu)的命名類的名稱都要以大寫字母“C”開頭，后跟一個或多個單詞。按實際情況，每個單詞的首字母大寫，保持文件名與類名一致。推薦的組成形式類的命名推薦用"名詞"或"形容詞名詞"的形式，例如："CAnalyzer", "CFastVect

6、or" .不同于C+類的概念，傳統(tǒng)的C結(jié)構(gòu)體只是一種將一組數(shù)據(jù)捆綁在一起的方式。傳統(tǒng)C結(jié)構(gòu)體的命名規(guī)則為：傳統(tǒng)C結(jié)構(gòu)體的命名傳統(tǒng)C結(jié)構(gòu)體的名稱全部由大寫字母組成，單詞間使用下劃線界定，例如："SERVICE_STATUS_S", "DRIVER_INFO" .1.3 函數(shù)函數(shù)的命名函數(shù)的名稱由一個或多個單詞組成。為便于界定，每個單詞的首字母要大寫。推薦的組成形式函數(shù)名應(yīng)當(dāng)使用"動詞"或者"動詞名詞"（動賓詞組）的形式。例如："GetName()", "SetValue()&q

7、uot;, "Erase()", "Reserve()" .保護成員函數(shù)保護成員函數(shù)的開頭應(yīng)當(dāng)加上一個下劃線“_”以示區(qū)別，例如："_SetState()" .私有成員函數(shù)類似地，私有成員函數(shù)的開頭建議加上兩個下劃線“_”，例如："_DestroyImp()" .不強制。虛函數(shù)虛函數(shù)習(xí)慣以“Do”開頭，如："DoRefresh()", "_DoEncryption()" .回調(diào)和事件處理函數(shù)回調(diào)和事件處理函數(shù)習(xí)慣以單詞“On”開頭。例如："OnTimer()&quo

8、t;, "OnExit()" .1.4 變量變量應(yīng)該是程序中使用最多的標識符了，變量的命名規(guī)范可能是一套C+命名準則中最重要的部分：變量的命名變量名由作用域前綴類型前綴一個或多個單詞組成。為便于界定，每個單詞的首字母要大寫。對于某些用途簡單明了的局部變量，也可以使用簡化的方式，如：i, j, k, x, y, z .作用域前綴作用域前綴標明一個變量的可見范圍。作用域可以有如下幾種：前綴說明無局部變量m_類的成員變量（member）sm_或ms_類的靜態(tài)成員變量（static member）s_靜態(tài)變量（static）g_外部全局變量（global）sg_靜態(tài)全局變量（sta

9、tic global）gg_進程間共享的共享數(shù)據(jù)段全局變量（global global）除非不得已，否則應(yīng)該盡可能少使用全局變量。類型前綴類型前綴標明一個變量的類型，可以有如下幾種：前綴說明n整型和位域變量（number）e_枚舉型變量（enumeration）強制要求c字符型變量（char）b布爾型變量（bool）f浮點型變量（float）p指針型變量和迭代子（pointer）強制要求pfn特別針對指向函數(shù)的指針變量和函數(shù)對象指針（pointer of function），強制要求arr數(shù)組(Array)str字符串，強制要求i類的實例（instance）對于經(jīng)常用到的類，也可以定義一些專門

10、的前綴，如：std:string和std:wstring類的前綴可以定義為"st"，std:vector類的前綴可以定義為"v"等等。類型前綴可以組合使用，例如"gc"表示字符數(shù)組，"ppn"表示指向整型的指針的指針等等。推薦的組成形式變量的名字應(yīng)當(dāng)使用"名詞"或者"形容詞名詞"。例如："nCode", "m_nState"，"nMaxWidth" .1.5 常量C+中引入了對常量的支持，常量的命名規(guī)則如下：常量的命

11、名常量名由類型前綴全大寫字母組成，單詞間通過下劃線來界定，如：cDELIMITER, nMAX_BUFFER .類型前綴的定義與變量命名規(guī)則中的相同。Define 要大寫，Const命名規(guī)則與普通變量一致。1.6 枚舉、聯(lián)合、typedef枚舉、聯(lián)合及typedef語句都是定義新類型的簡單手段，它們的命名規(guī)則為：枚舉、聯(lián)合、typedef的命名枚舉、聯(lián)合、typedef語句生成的類型名由全大寫字母組成，單詞間通過下劃線來界定，如：FAR_PROC, ERROR_TYPE .1.7 宏、枚舉值宏、枚舉值的命名宏和枚舉值由全大寫字母組成，單詞間通過下劃線來界定，如：ERROR_UNKNOWN, O

12、P_STOP .2 文件結(jié)構(gòu)2.1 文件頭注釋所有C+的源文件均必須包含一個規(guī)范的文件頭，文件頭包含了該文件的名稱、功能概述、作者、版權(quán)和版本歷史信息等內(nèi)容。標準文件頭的格式為：/*! file*<PRE>文件名       : <文件名>文件描述 : <描述該文件實現(xiàn)的主要功能> 作者         : <作者部門和姓名>版本      

13、;   : <當(dāng)前版本號>創(chuàng)建時間-備注         : <其它說明> 建議使用備注，不強制要求-</PRE>*/ 每行不要超過80個字符的寬度。強制要求2.2 頭文件頭文件通常由以下幾部分組成：文件頭注釋所有C+的源文件均必須包含一個規(guī)范的文件頭，文件頭包含了該文件的名稱、功能概述、作者、版權(quán)和版本歷史信息等內(nèi)容。預(yù)處理塊為了防止頭文件被重復(fù)引用，應(yīng)當(dāng)用ifndef/define/endif結(jié)構(gòu)產(chǎn)生預(yù)處理塊。函數(shù)和類/結(jié)構(gòu)的聲明等聲明模塊的接口

14、需要包含的內(nèi)聯(lián)函數(shù)定義文件（如果有的話）如果類中的內(nèi)聯(lián)函數(shù)較多，或者一個頭文件中包含多個類的定義（不推薦），可以將所有內(nèi)聯(lián)函數(shù)定義放入一個單獨的內(nèi)聯(lián)函數(shù)定義文件中，并在類聲明之后用“#include”指令把它包含進來。頭文件的編碼規(guī)則：-用 #include <filename.h> 格式來引用標準庫和系統(tǒng)庫的頭文件（編譯器將從標準庫目錄開始搜索）。用 #include "filename.h" 格式來引用當(dāng)前工程中的頭文件（編譯器將從該文件所在目錄開始搜索）。如果在一個頭件中定義了多個類或者多組接口（不推薦），為了便于瀏覽，應(yīng)該在每個類/每組接口間使用分割帶把

15、它們相互分開。一個頭文件內(nèi)只能定義一個類或一組接口。 如上所述，在內(nèi)聯(lián)函數(shù)較多的情況下，為了避免頭文件過長、版面混亂，可以將所有的內(nèi)聯(lián)函數(shù)定義移到一個單獨的文件中去，然后再用#include指令將它包含到類聲明的后面。這樣的文件稱為一個內(nèi)聯(lián)函數(shù)定義文件。按照慣例，應(yīng)該將這個文件命名為“filename.inl”，其中“filename”與相應(yīng)的頭文件和實現(xiàn)文件相同。內(nèi)聯(lián)函數(shù)定義文件由以下幾部分組成：文件頭注釋每內(nèi)聯(lián)函數(shù)定義文件都應(yīng)該由一個規(guī)范的文件頭注釋作為開始內(nèi)聯(lián)函數(shù)定義內(nèi)聯(lián)函數(shù)的實現(xiàn)體內(nèi)聯(lián)函數(shù)定義文件的編碼規(guī)則：分割多組接口（如果有的話）如果在一個內(nèi)聯(lián)函數(shù)定義文件中定義了多個類或

16、者多組接口的內(nèi)聯(lián)函數(shù)（不推薦），必須在每個類/每組接口間使用分割帶把它們相互分開。文件組成中為什么沒有預(yù)處理塊？與頭文件不同，內(nèi)聯(lián)函數(shù)定義文件通常不需要定義預(yù)處理塊，這是因為他們總是被包含在與其相應(yīng)的頭文件預(yù)處理塊內(nèi)。 2.3 實現(xiàn)文件實現(xiàn)文件包含所有數(shù)據(jù)和代碼的實現(xiàn)體。實現(xiàn)文件的格式為：文件頭注釋每個實現(xiàn)文件都應(yīng)該由一個規(guī)范的文件頭注釋作為開始引用聲明了此文件實現(xiàn)的類、函數(shù)及數(shù)據(jù)的頭文件將僅與實現(xiàn)相關(guān)的接口包含在實現(xiàn)文件里（而不是頭文件中）是一個非常好的編程習(xí)慣。這樣可以有效地屏蔽不應(yīng)該暴露的實現(xiàn)細節(jié)，將實現(xiàn)改變對其它模塊的影響降低到最少 。數(shù)據(jù)和函數(shù)的定義實現(xiàn)文件的編碼規(guī)則：在本

17、地（靜態(tài)）定義和外部定義間，以及不同接口或不同類的實現(xiàn)之間，應(yīng)使用分割帶相互分開。 3 代碼風(fēng)格與版式代碼風(fēng)格的重要性怎么強調(diào)都不過分。一段稍長一點的無格式代碼基本上就是不可讀的。 先來看一下這方面的整體原則： 建議使用空行分隔程序段落?？招械皿w（不過多也不過少）將使程序的布局更加清晰?？招胁粫速M內(nèi)存，雖然打印含有空行的程序是會多消耗一些紙張，但是值得。所以不要舍不得用空行。· 在每個類聲明之后、每個函數(shù)定義結(jié)束之后都要加2行空行。· 在一個函數(shù)體內(nèi)，邏揖上密切相關(guān)的語句之間不加空行，其它地方應(yīng)加空行分隔。 3.1 語句與代碼行·

18、一行代碼只做一件事情，如只定義一個變量，或只寫一條語句。這樣的代碼容易閱讀，并且方便于寫注釋。· "if"、"for"、"while"、"do"、"try"、"catch" 等語句自占一行，執(zhí)行語句不得緊跟其后。不論執(zhí)行語句有多少都要加 " " 。這樣可以防止書寫和修改代碼時出現(xiàn)失誤。3.2 縮進和對齊· 程序的分界符 "" 和 "" 應(yīng)獨占一行并且位于同一列，同時與引用它們的語句左對齊。

19、3; " " 之內(nèi)的代碼塊在 "" 右邊一個四個空格處左對齊。如果出現(xiàn)嵌套的 " "，則使用縮進對齊。例如： void Function(int x)  CSessionLock iLock(mxLock);    for (初始化; 終止條件; 更新)            / .        try &

20、#160;          / .        catch (const exception& err)            / .        catch (.) 3.3 最大長度代碼行最大長度宜控制在70至80個字符以內(nèi)。代碼行不要過長，否則眼睛看不過來，也不便于打?。?/p>

21、2009年更新：隨著GUI開發(fā)環(huán)境和高分寬屏的普及，此規(guī)則可以視情況適當(dāng)放寬）。3.4 長行拆分長表達式要在低優(yōu)先級操作符處拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要進行適當(dāng)?shù)目s進，使排版整齊，語句可讀。例如：if (very_longer_variable1 >= very_longer_variable2)    && (very_longer_variable3 <= very_longer_variable4)    && (very_longer_v

22、ariable5 <= very_longer_variable6)    DoSomething();3.5    空格的使用1.        關(guān)鍵字之后要留空格。象 "const"、"virtual"、"inline"、"case" 等關(guān)鍵字之后至少要留一個空格，否則無法辨析關(guān)鍵字。象 "if"、"for"、"while"、&

23、quot;catch" 等關(guān)鍵字之后應(yīng)留一個空格再跟左括號 "("，以突出關(guān)鍵字。2.        函數(shù)名之后不要留空格，緊跟左括號 "("，以與關(guān)鍵字區(qū)別。3.        "(" 向后緊跟。而 ")"、","、"" 向前緊跟，緊跟處不留空格。4.      &#

24、160; "," 之后要留空格，如 Function(x, y, z)。如果 "" 不是一行的結(jié)束符號，其后要留空格，如 for (initialization; condition; update)。5.        賦值操作符、比較操作符、算術(shù)操作符、邏輯操作符、位域操作符，如"="、"+=" ">="、"<="、"+"、"*"、"%&qu

25、ot;、"&&"、"|"、"<<", "" 等二元操作符的前后應(yīng)當(dāng)加空格。6.        一元操作符如 "!"、""、"+"、"-"、"&"（地址運算符）等前后不加空格。7.        象""、".&quo

26、t;、"->"這類操作符前后不加空格。8.        對于表達式比較長的 for、do、while、switch 語句和 if 語句，為了緊湊起見可以適當(dāng)?shù)厝サ粢恍┛崭?，?for (i=0; i<10; i+) 和 if (a<=b) && (c<=d) 等。例如：void Func1(int x, int y, int z);    / 良好的風(fēng)格void Func1 (int x,int y,in

27、t z);     / 不良的風(fēng)格/ =if (year >= 2000)         / 不良的風(fēng)格if(year>=2000)            / 不良的風(fēng)格if (a>=b) && (c<=d)     / 良好的

28、風(fēng)格if(a>=b&&c<=d)            / 不良的風(fēng)格/ =for (i=0; i<10; i+)      / 良好的風(fēng)格for(i=0;i<10;i+)         / 不良的風(fēng)格for (i = 0; I < 10; i +) /

29、0;過多的空格/ =x = a < b ? a : b;        / 良好的風(fēng)格x=a<b?a:b;                / 不好的風(fēng)格/ =int* x = &y;              /

30、0;良好的風(fēng)格int * x = & y;            / 不良的風(fēng)格/ =array5 = 0;             / 不要寫成 array 5 = 0;a.Function();            

31、 / 不要寫成 a . Function();b->Function();            / 不要寫成 b -> Function(); 3.6 修飾符的位置為便于理解，應(yīng)當(dāng)將修飾符 "*" 和 "&" 緊靠數(shù)據(jù)類型。 例如：char* name;int* x;int  y;    / 為避免y被誤解為指針，這里必須分行寫。int* Fun

32、ction(void* p);  3.7 注釋· 注釋的位置應(yīng)與被描述的代碼相鄰，可以放在代碼的上方或右方，不可放在下方。· 邊寫代碼邊注釋，修改代碼同時修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除。· 注釋應(yīng)當(dāng)準確、易懂，防止注釋有二義性。錯誤的注釋不但無益反而有害。· 當(dāng)代碼比較長，特別是有多重嵌套時，應(yīng)當(dāng)在一些段落的結(jié)束處加注釋，便于閱讀。4 注釋分類說明4.1 源文件頭部注釋Ø 列出：版權(quán)、作者、編寫日期和描述。Ø 示例：/*Copyright:buptAuthor:Date:2

33、010-08-25Description:描述主要實現(xiàn)的功能*/每行不要超過80個字符的寬度。4.2 函數(shù)頭部注釋Ø 列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、等。Ø 示例：下面這段函數(shù)的注釋比較標準，當(dāng)然，并不局限于此格式，但上述信息建議要包含在內(nèi)。/*Function:       / 函數(shù)名稱Description:    / 函數(shù)功能、性能等的描述Input:        &#

34、160; / 輸入?yún)?shù)說明，包括每個參數(shù)的作                  / 用、取值說明及參數(shù)間關(guān)系。Output:         / 對輸出參數(shù)的說明。Return:         / 函數(shù)返回值的說明Others:   &#

35、160;     / 其它說明*/如果其命名不是充分自注釋的，必須加以注釋。對數(shù)據(jù)結(jié)構(gòu)的注釋應(yīng)放在其上方相鄰位置，不可放在下面；對結(jié)構(gòu)中的每個域的注釋放在此域的右方。Ø 示例：可按如下形式說明枚舉/數(shù)據(jù)/聯(lián)合結(jié)構(gòu)。/* sccp interface with sccp user primitive message name */enum SCCP_USER_PRIMITIVE    N_UNITDATA_IND, /* sccp notify sccp user unit data come */ 

36、60;  N_NOTICE_IND,   /* sccp notify user the No.7 network can not */                    /* transmission this message */    N_UNITDATA_REQ, /* sccp user's unit data transmi

37、ssion request*/;4.3 全局變量的注釋Ø 包括對其功能、取值范圍、哪些函數(shù)或過程存取它以及存取時注意事項等的說明。示例：/* The ErrorCode when SCCP translate */* Global Title failure, as follows */      / 變量作用、含義注釋總是加在程序的需要一個概括性說明或不易理解或易理解錯的地方。注釋語言應(yīng)該簡練、易懂而又含義準確，避免二義性；所采用的語種首選是中文，如有輸入困難、編譯環(huán)境限制或特殊需求也可采用英文。注釋應(yīng)與其描述的代碼相近，

38、對代碼的注釋統(tǒng)一放在其上方，避免在一行代碼或表達式中間使用注釋。上方注釋與其上面的代碼用空行隔開（較緊湊的代碼除外）。注意：注釋應(yīng)與所描述內(nèi)容進行同樣的縮進。附：QT控件命名規(guī)范控件名稱命名前綴示例命名QPushButtonbtnbtnOKQToolButtontoolBtntoolBtnSelectQRadioButtonradioBtnradioBtnQCheckBoxcheckBoxcheckBoxManQListViewlistViewlistViewFriendQTreeViewtreeViewtreeVeiwFriendQTableViewtableViewtableViewFri

39、endQColumnViewcolumnVewcolumnViewFriendQListWidgetlistWidgetlistWidgetFriendQTreeWidgettreeWidgettreeWidgetFriendQTableWidgettableWidgettableWidgetFriendQGroupBoxgroupBoxgroupBoxFriendInfoQScrollAreascrollAreascrollAreaFriendQToolBoxtoolboxtoolBoxFriendQTabWidgettabWidgettabWidgetFriendQStackWidgetstackWidgetstackWidgetFriendQFrameframeframeBackgroundQWidgetwidgetwidgetFriendQComboBoxcomboBoxcomboBoxLoginUserQFontComboBoxfontComboBoxfontComboBoxSelectQLineEditedtedtSignatureQTextEdittextEdttextEdtFriendInfoQPlainTextEditplainTextEdtplain