【正文】 sion: // 版本信息 Function List: // 主要函數(shù)及其功能 1. History: // 歷史修改記錄 author time version desc David 96/10/12 build this moudle ***********************************************************/ 說(shuō)明： Description一項(xiàng)描述本文件的內(nèi)容、功能、內(nèi)部各部分之間的關(guān)系及本文件與其它文件關(guān)系等。 History是修改歷史記錄列表，每條修改記錄應(yīng)包括修改日期、修改者及修改內(nèi)容簡(jiǎn)述。 185。24：函數(shù)頭部應(yīng)進(jìn)行注釋，列出：函數(shù)的目的 /功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào)用關(guān)系（函數(shù)、表）等。 示例：下面這段函數(shù)的注釋比較標(biāo)準(zhǔn)，當(dāng)然，并不局限于此格式，但上述信息建議要包含在內(nèi)。 /************************************************* Function: // 函數(shù)名稱 Description: // 函數(shù)功能、性能等的描述 Calls: // 被本函數(shù)調(diào)用的函數(shù)清單 Called By: // 調(diào)用本函數(shù)的函數(shù)清單 Table Accessed: // 被訪問的表（此項(xiàng)僅對(duì)于牽扯到數(shù)據(jù)庫(kù)操作的程序） Table Updated: // 被修改的表（此項(xiàng)僅對(duì)于牽扯到數(shù)據(jù)庫(kù)操作的程 序） Input: // 輸入?yún)?shù)說(shuō)明，包括每個(gè)參數(shù)的作 // 用、取值說(shuō)明及參數(shù)間關(guān)系。 Output: // 對(duì)輸出參數(shù)的說(shuō)明。 Return: // 函數(shù)返回值的說(shuō)明 Others: // 其它說(shuō)明 *************************************************/ 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 11 185。25：邊寫代碼邊注釋，修改代碼同時(shí)修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用 的注釋要?jiǎng)h除。 185。26：注釋的內(nèi)容要清楚、明了，含義準(zhǔn)確，防止注釋二義性。 說(shuō)明：錯(cuò)誤的注釋不但無(wú)益反而有害。 規(guī)則 27：避免在注釋中使用縮寫，特別是非常用縮寫。 說(shuō)明：在使用縮寫時(shí)或之前，應(yīng)對(duì)縮寫進(jìn)行必要的說(shuō)明。 185。28：注釋應(yīng)與其描述的代碼相近，對(duì)代碼的注釋應(yīng)放在其上方或右方（對(duì)單條語(yǔ)句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。 示例：如下例子不符合規(guī)范。 例 1： /* get replicate sub system index and indicator */ 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)如下書寫 /* get replicate sub system index and indicator */ repssn_ind = ssn_data[index].repssn_index。 repssn_ni = ssn_data[index].ni。 185。29：對(duì)于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時(shí)都必須加以注釋，說(shuō)明其物理含義。變量、常量、宏的注釋應(yīng)放在其上方相鄰位置或右方。 示例： /* active statistic task number */ define MAX_ACT_TASK_NUMBER 1000 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 12 define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */ 185。210：數(shù)據(jù)結(jié)構(gòu)聲明 (包括數(shù)組、結(jié)構(gòu)、類、枚舉等 )，如果其命名不是充分自注釋的，必須加以注釋。對(duì)數(shù)據(jù)結(jié)構(gòu)的注釋應(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 { 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*/ }。 185。211：全局變量要有較詳細(xì)的注釋，包括對(duì)其功能、取值范圍、哪些函數(shù)或過程存取它以及存取時(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。 185。212：注釋與所描述內(nèi)容進(jìn)行同樣的縮排。 說(shuō)明：可使程序排版整齊，并方便注釋的閱讀與理解。 示例：如下例子，排版不整齊，閱讀稍感不 方便。 void example_fun( void ) { /* code one ments */ CodeBlock One 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 13 /* code two ments */ CodeBlock Two } 應(yīng)改為如下布局。 void example_fun( void ) { /* code one ments */ CodeBlock One /* code two ments */ CodeBlock Two } 185。213：將注釋與其上面的代碼用空行隔開。 示例：如下例子，顯得代碼過于緊湊。 /* code one ments */ program code one /* code two ments */ program code two 應(yīng)如下書寫 /* code one ments */ program code one /* code two ments */ program code two 185。214：對(duì)變量的定義和分支語(yǔ)句（條件分支、循環(huán)語(yǔ)句等）必須編寫注釋。 說(shuō)明：這些語(yǔ) 句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對(duì)于維護(hù)人員來(lái)說(shuō)，良好的注釋幫助更好的理解程序，有時(shí)甚至優(yōu)于看設(shè)計(jì)文檔。 185。215：對(duì)于 switch語(yǔ)句下的 case語(yǔ)句，如果因?yàn)樘厥馇闆r需要處理完一個(gè) case后進(jìn)入下一個(gè) case處理，必須在該 case語(yǔ)句處理完、下一個(gè) case語(yǔ)句前加上明確的注釋。 說(shuō)明：這樣比較清楚程序編寫者的意圖，有效防止無(wú)故遺漏 break語(yǔ)句。 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 14 示例（注意斜體加粗部分）： 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。 case CMD_C: ProcessC()。 break。 case CMD_D: ProcessD()。 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 15 break。 ... 189。21：避免在一行代碼或表達(dá)式的中間插入注釋。 說(shuō)明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。 189。22：通過對(duì)函數(shù)或過程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的。 說(shuō)明：清晰準(zhǔn)確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。 189。23：在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額外的信息。 說(shuō)明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重復(fù)注釋信息。 示例：如下注釋意義不大。 /* if receive_flag is TRUE */ if (receive_flag) 而如下的注釋則給出了額外有用的信息。 /* if mtp receive a message from links */ if (receive_flag) 189。24：在程序塊的結(jié)束行右方加注釋標(biāo)記，以表明某程序塊的結(jié)束。 說(shuō)明：當(dāng)代碼段較長(zhǎng)，特別是多重嵌套時(shí)，這樣做可以使代碼更清晰，更便于閱讀。 示例：參見如下例子。 if (...) { // program code while (index MAX_INDEX) { // program code } /* end of while (index MAX_INDEX) */ // 指明該條 while語(yǔ)句結(jié)束 } /* end of if (...)*/ // 指明是哪條 if語(yǔ)句結(jié)束 軟件編程規(guī)范總則 2 注釋 僅供內(nèi)部使用 16 189。25：注釋格式盡量統(tǒng)一，建議使用“ /* ?? */”。 189。26：注釋應(yīng)考慮程序易讀及外觀排版的因素，使用的語(yǔ)言若是中、英兼有的，建議多使用中文，除非能用非常流利準(zhǔn)確的英文表達(dá)。 說(shuō)明：注釋語(yǔ)言不統(tǒng)一，影響程序易讀性和外觀排版，出 于對(duì)維護(hù)人員的考慮，建議使用中文。 軟件編程規(guī)范總則 3 標(biāo)志符命名 僅供內(nèi)部使用 17 3 標(biāo)識(shí)符命名 185。31：標(biāo)識(shí)符的命名要清晰、明了，有明確含義，同時(shí)使用完整的單詞或大家基本可以理解的縮寫，避免使人產(chǎn)生誤解。 說(shuō)明：較短的單詞可通過去掉“元音”形成縮寫；較長(zhǎng)的單詞可取單詞的頭幾個(gè)字母形成