【導(dǎo)讀】--. --. 代碼規(guī)范文檔。第2頁(yè)共69頁(yè)。目錄

　　

【正文】 合規(guī)范。 例 1： /* get replicate sub system index and indicator */ 第 15 頁(yè) 共 69 頁(yè) repssn_ind = ssn_data[index].repssn_index。 repssn_ni = ssn_data[index].ni。 例 2： repssn_ind = ssn_data[index].repssn_index。 repssn_ni = ssn_data[index].ni。 /* get replicate sub system index and indicator */ 應(yīng)如下書(shū)寫(xiě) /* get replicate sub system index and indicator */ repssn_ind = ssn_data[index].repssn_index。 repssn_ni = ssn_data[index].ni。 變量、常量注釋 對(duì)于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時(shí)都必須加以注釋，說(shuō)明其物理含義。變量、常量、宏的注釋?xiě)?yīng)放在其上方相鄰位置或右方。 示例： /* active statistic task number */ define MAX_ACT_TASK_NUMBER 1000 define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */ 數(shù)據(jù)結(jié)構(gòu)的注釋 數(shù)據(jù)結(jié)構(gòu)聲明 (包括數(shù)組、結(jié)構(gòu)、類、枚舉等 )，如果其命名不是充分自注釋的，必須加以注釋。對(duì)數(shù)據(jù)結(jié)構(gòu)的注釋?xiě)?yīng)放在其上方相鄰位置，不可放在下面；對(duì)結(jié)構(gòu)中的每個(gè)域的注釋放在此域的右方。 示例：可按如下形式說(shuō)明枚舉 /數(shù)據(jù) /聯(lián)合結(jié)構(gòu)。 /* sccp interface with sccp user primitive message name */ enum SCCP_USER_PRIMITIVE { 第 16 頁(yè) 共 69 頁(yè) N_UNITDATA_IND, /* sccp notify sccp user unit data e */ N_NOTICE_IND, /* sccp notify user the work can not */ /* transmission this message */ N_UNITDATA_REQ, /* sccp user39。s unit data transmission request*/ }。 全局變量 全局變量要有較詳細(xì)的注釋，包括對(duì)其功能、取值范圍、哪些函數(shù)或過(guò)程存取它以及存取時(shí)注意事項(xiàng)等的說(shuō)明 。 示例： /* The ErrorCode when SCCP translate */ /* Global Title failure, as follows */ // 變量作用、含義 /* 0 － SUCCESS 1 － GT Table error */ /* 2 － GT error Others － no use */ // 變量取值范圍 /* only function SCCPTranslate() in */ /* this modual can modify it, and other */ /* module can visit it through call */ /* the function GetGTTransErrorCode() */ // 使用方法 BYTE g_GTTranErrorCode。 注釋縮排 注釋與所描述內(nèi)容進(jìn)行同樣的縮排。 說(shuō)明：可使程序排版整齊，并方便注釋的閱讀與理解。 示例：如下例子，排版不整齊， 閱讀稍感不方便。 void example_fun( void ) { /* code one ments */ CodeBlock One /* code two ments */ CodeBlock Two 第 17 頁(yè) 共 69 頁(yè) } 應(yīng)改為如下布局。 void example_fun( void ) { /* code one ments */ CodeBlock One /* code two ments */ CodeBlock Two } 注釋與代碼之間空行 將注釋與其上面的代碼用空行隔開(kāi)。 示例：如下例子，顯得代碼過(guò)于緊湊。 /* code one ments */ program code one /* code two ments */ program code two 應(yīng)如下書(shū)寫(xiě) /* code one ments */ program code one /* code two ments */ program code two 變量定義、分支語(yǔ)句 對(duì)變量的定義和分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等 ）必須編寫(xiě)注釋。 說(shuō)明：這些語(yǔ)句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對(duì)于維護(hù)人員來(lái)說(shuō)，良好的注釋幫助更好的理 第 18 頁(yè) 共 69 頁(yè) 解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。 示例（注意斜體加粗部分）： case CMD_UP: ProcessUp()。 break。 case CMD_DOWN: ProcessDown()。 break。 case CMD_FWD: ProcessFwd()。 if (...) { ... break。 } else { ProcessCFW_B()。 // now jump into case CMD_A } case CMD_A: ProcessA()。 break。 case CMD_B: ProcessB()。 break。 第 19 頁(yè) 共 69 頁(yè) case CMD_C: ProcessC()。 break。 case CMD_D: ProcessD()。 break。 ... 其他 避免在一行 代碼或表達(dá)式的中間插入注釋。 說(shuō)明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。 通過(guò)對(duì)函數(shù)或過(guò)程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的。 說(shuō)明：清晰準(zhǔn)確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。 在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息。 說(shuō)明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒(méi)必要的重復(fù)注釋信息。 示例：如下注釋意義不大。 /* if receive_flag is TRUE */ if (receive_flag) 而如下的注釋則給出了額外有用的信息。 /* if mtp receive a message from links */ if (receive_flag) 第 20 頁(yè) 共 69 頁(yè) 在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束。 說(shuō)明：當(dāng)代碼段較長(zhǎng)，特別是多重嵌套時(shí)，這樣做可以使代碼更清晰，更便于閱讀。 示例：參見(jiàn)如下例子。 if (...) { // program code while (index MAX_INDEX) { // program code } /* end of while (index MAX_INDEX) */ // 指明該條 while語(yǔ)句結(jié)束 } /* end of if (...)*/ // 指明是哪條 if語(yǔ)句結(jié)束 注釋格式盡量統(tǒng)一，建議使用“ /* ?? */”。 注釋?xiě)?yīng)考慮程序易讀及外觀排版的因素，使用的語(yǔ)言若是中、英兼有的，建議多使用中文，除非能用非常流利準(zhǔn)確的英文表達(dá)。 說(shuō)明：注釋語(yǔ)言不統(tǒng)一，影響程序易讀性和外觀排版，出于對(duì)維護(hù)人員的考慮，建議使用 中文。 4 標(biāo)識(shí)符命名 命名清晰 標(biāo)識(shí)符的命名要清晰、明了，有明確含義，同時(shí)使用完整的單詞或大家基本可以理解的縮寫(xiě)，避免使人產(chǎn)生誤解。 說(shuō)明：較短的單詞可通過(guò)去掉“元音”形成縮寫(xiě)；較長(zhǎng)的單詞可取單詞的頭幾個(gè)字母形成 縮寫(xiě)；一些單詞有大家公認(rèn)的縮寫(xiě)。 示例：如下單詞的縮寫(xiě)能夠被大家基本認(rèn)可。 第 21 頁(yè) 共 69 頁(yè) temp 可縮寫(xiě)為 tmp 。 flag 可縮寫(xiě)為 flg 。 statistic 可縮寫(xiě)為 stat 。 increment 可縮寫(xiě)為 inc 。 message 可縮寫(xiě)為 msg 。 特殊命名需注釋 命名中若使用特殊 約定或縮寫(xiě)，則要有注釋說(shuō)明。 說(shuō)明：應(yīng)該在源文件的開(kāi)始之處，對(duì)文件中所使用的縮寫(xiě)或約定，特別是特殊的縮寫(xiě)，進(jìn) 行必要的注釋說(shuō)明。 命名風(fēng)格保持一致 自己特有的命名風(fēng)格，要自始至終保持一致，不可來(lái)回變化。 說(shuō)明：個(gè)人的命名風(fēng)格，在符合所在項(xiàng)目組或產(chǎn)品組的命名規(guī)則的前提下，才可使用。（即 命名規(guī)則中沒(méi)有規(guī)定到的地方才可有個(gè)人命名風(fēng)格）。 變量命名 對(duì)于變量命名，禁止取單個(gè)字符（如 i、 j、 k...），建議除了要有具體含義外，還能表明其變量類型、數(shù)據(jù)類型等，但 i、 j、 k 作局部循環(huán)變量是允許的。 說(shuō)明：變量，尤其 是局部變量，如果用單個(gè)字符表示，很容易敲錯(cuò)（如 i寫(xiě)成 j），而編譯時(shí)又檢查不出來(lái)，有可能為了這個(gè)小小的錯(cuò)誤而花費(fèi)大量的查錯(cuò)時(shí)間。 示例：下面所示的局部變量名的定義方法可以借鑒。 int liv_Width 其變量名解釋如下： l 局部變量（ Local） （其它： g 全局變量（ Global） ...） i 數(shù)據(jù)類型（ Interger） v 變量（ Variable） （其它： c 常量（ Const） ...） Width 變量含義 這樣可以防止局部變量與 全局變量重名。 第 22 頁(yè) 共 69 頁(yè) 命名規(guī)范與系統(tǒng)風(fēng)格一致 命名規(guī)范必須與所使用的系統(tǒng)風(fēng)格保持一致，并在同一項(xiàng)目中統(tǒng)一，比如采用 UNIX 的全小寫(xiě)加下劃線的風(fēng)格或大小寫(xiě)混排的方式，不要使用大小寫(xiě)與下劃線混排的方式，用作特殊標(biāo)識(shí)如標(biāo)識(shí)成員變量或全局變量的 m_和 g_，其后加上大小寫(xiě)混排的方式是允許的。 示例： Add_User不允許， add_user、 AddUser、 m_AddUser允許。 其他 除非必要，不要用數(shù)字或較奇怪的字符來(lái)定義標(biāo)識(shí)符。 示例：如下命名，使人產(chǎn)生疑惑。 define _EXAMPLE_0_TES