編程規(guī)范和范例
目 錄 |1 排版 |6 | |2 注釋 |11 | |3 標識符命名 |18 | |4 可讀性 |20 | |5 變量、結構 |22 | |6 函數(shù)、過程 |28 | |7 可測性 |36 | |8 程序效率 |40 | |9 質(zhì)量保證 |44 | |10 代碼編輯、編譯、審查 |50 | |11 代碼測試、維護 |52 | |12 宏 |53 | 1 排版 1-1：程序塊要采用縮進風格編寫，縮進的空格數(shù)為4個。 說明：對于由開發(fā)工具自動生成的代碼可以有不一致。 1-2：相對獨立的程序塊之間、變量說明之后必須加空行。 示例：如下例子不符合規(guī)范。 if (!valid_ni(ni)) { ... // program code } repssn_ind = ssn_data[index].repssn_index; repssn_ni = ssn_data[index].ni; 應如下書寫 if (!valid_ni(ni)) { ... // program code } repssn_ind = ssn_data[index].repssn_index; repssn_ni = ssn_data[index].ni; 1- 3：較長的語句（>80字符）要分成多行書寫，長表達式要在低優(yōu)先級操作符處劃分新行 ，操作符放在新行之首，劃分出的新行要進行適當?shù)目s進，使排版整齊，語句可讀。 示例： perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN + STAT_SIZE_PER_FRAM * sizeof( _UL ); act_task_table[frame_id * STAT_TASK_CHECK_NUMBER + index].occupied = stat_poi[index].occupied; act_task_table[taskno].duration_true_or_false = SYS_get_sccp_statistic_state( stat_item ); report_or_not_flag = ((taskno < MAX_ACT_TASK_NUMBER) && (n7stat_stat_item_valid (stat_item)) && (act_task_table[taskno].result_data != 0)); 1- 4：循環(huán)、判斷等語句中若有較長的表達式或語句，則要進行適應的劃分，長表達式要在 低優(yōu)先級操作符處劃分新行，操作符放在新行之首。 示例： if ((taskno < max_act_task_number) && (n7stat_stat_item_valid (stat_item))) { ... // program code } for (i = 0, j = 0; (i < BufferKeyword[word_index].word_length) && (j < NewKeyword.word_length); i++, j++) { ... // program code } for (i = 0, j = 0; (i < first_word_length) && (j ），后不 應加空格。 說明：采用這種松散方式編寫代碼的目的是使代碼更加清晰。 由于留空格所產(chǎn)生的清晰性是相對的，所以，在已經(jīng)非常清晰的語句中沒有必要再留 空格，如果語句已足夠清晰則括號內(nèi)側(cè)(即左括號后面和右括號前面)不需要加空格， 多重括號間不必加空格，因為在C/C++語言中括號已經(jīng)是最清晰的標志了。 在長語句中，如果需要加的空格非常多，那么應該保持整體清晰，而在局部不加空格 。給操作符留空格時不要連續(xù)留兩個以上空格。 示例： (1) 逗號、分號只在后面加空格。 int a, b, c; (2)比較操作符, 賦值操作符"="、 "+="，算術操作符"+"、"%"，邏輯操作符"&&"、"&"，位域操作符 ""、"."前后不加空格。 p->id = pid; // "->"指針前后不加空格 (5) if、for、while、switch等與后面的括號間應加空格，使if等關鍵字更為突出、明顯 。 if (a >= b && c > d) 1-1：一行程序以小于80字符為宜，不要寫得過長。 2 注釋 2-1：一般情況下，源程序有效注釋量必須在20％以上。 說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加了，注釋不宜太多 也不能太少，注釋語言必須準確、易懂、簡潔。 2- 2：說明性文件（如頭文件.h文件、.inc文件、.def文件、編譯說明文件.cfg等）頭部應 進行注釋，注釋必須列出：版權說明、版本號、生成日期、作者、內(nèi)容、功能、與其它 文件的關系、修改日志等，頭文件的注釋中還應有函數(shù)功能簡要說明。 示例：下面這段頭文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建 議要包含在內(nèi)。 /************************************************* Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. File name: // 文件名 Author: Version: Date: // 作者、版本及完成日期 Description: // 用于詳細說明此程序文件完成的主要功能，與其他模塊 // 或函數(shù)的接口，輸出值、取值范圍、含義及參數(shù)間的控 // 制、順序、獨立或依賴等關系 Others: // 其它內(nèi)容的說明 Function List: // 主要函數(shù)列表，每條記錄應包括函數(shù)名及功能簡要說明 1. .... History: // 修改歷史記錄列表，每條修改記錄應包括修改日期、修改 // 者及修改內(nèi)容簡述 1. Date: Author: Modification: 2. ... *************************************************/ 2- 3：源文件頭部應進行注釋，列出：版權說明、版本號、生成日期、作者、模塊目的/功 能、主要函數(shù)及其功能、修改日志等。 示例：下面這段源文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建 議要包含在內(nèi)。 /************************************************************ Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. FileName: test.cpp Author: Version : Date: Description: // 模塊描述 Version: // 版本信息 Function List: // 主要函數(shù)及其功能 1. ------- History: // 歷史修改記錄 David 96/10/12 1.0 build this moudle ***********************************************************/ 說明：Description一項描述本文件的內(nèi)容、功能、內(nèi)部各部分之間的關系及本文件 與其它文件關系等。History是修改歷史記錄列表，每條修改記錄應包括修改日期、 修改者及修改內(nèi)容簡述。 2- 4：函數(shù)頭部應進行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào) 用關系（函數(shù)、表）等。 示例：下面這段函數(shù)的注釋比較標準，當然，并不局限于此格式，但上述信息建議要 包含在內(nèi)。 /************************************************* Function: // 函數(shù)名稱 Description: // 函數(shù)功能、性能等的描述 Calls: // 被本函數(shù)調(diào)用的函數(shù)清單 Called By: // 調(diào)用本函數(shù)的函數(shù)清單 Table Accessed: // 被訪問的表（此項僅對于牽扯到數(shù)據(jù)庫操作的程序） Table Updated: // 被修改的表（此項僅對于牽扯到數(shù)據(jù)庫操作的程序） Input: // 輸入?yún)?shù)說明，包括每個參數(shù)的作 // 用、取值說明及參數(shù)間關系。 Output: // 對輸出參數(shù)的說明。 Return: // 函數(shù)返回值的說明 Others: // 其它說明 *************************************************/ 2- 5：邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。不再 有用的注釋要刪除。 2-6：注釋的內(nèi)容要清楚、明了，含義準確，防止注釋二義性。 說明：錯誤的注釋不但無益反而有害。 規(guī)則2-7：避免在注釋中使用縮寫，特別是非常用縮寫。 說明：在使用縮寫時或之前，應對縮寫進行必要的說明。 2- 8：注釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方（對單條語句的注釋 ）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。 示例：如下例子不符合規(guī)范。 例1： /* get replicate sub system index and net 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 net indicator */ 應如下書寫 /* get replicate sub system index and net indicator */ repssn_ind = ssn_data[index].repssn_index; repssn_ni = ssn_data[index].ni; 2- 9：對于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時都必須 加以注釋，說明其物理含義。變量、常量、宏的注釋應放在其上方相鄰位置或右方。 示例： /* active statistic task number */ #define MAX_ACT_TASK_NUMBER 1000 #define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */ 2- 10：數(shù)據(jù)結構聲明(包括數(shù)組、結構、類、枚舉等)，如果其命名不是充分自注釋的，必 須加以注釋。對數(shù)據(jù)結構的注釋應放在其上方相鄰位置，不可放在下面；對結構中的每 個域的注釋放在此域的右方。 示例：可按如下形式說明枚舉/數(shù)據(jù)/聯(lián)合結構。 /* sccp interface with sccp user primitive message name */ enum SCCP_USER_PRIMITIVE { N_UNITDATA_IND, /* sccp notify sccp user unit data come */ N_NOTICE_IND, /* sccp notify user the No.7 network can not */ /* transmission this message */ N_UNITDATA_REQ, /* sccp user’s unit data transmission request*/ }; 2- 11：全局變量要有較詳細的注釋，包括對其功能、取值范圍、哪些函數(shù)或過程存取它以 及存取時注意事項等的說明。 示例： /* 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; 2-12：注釋與所描述內(nèi)容進行同樣的縮排。 說明：可使程序排版整齊，并方便注釋的閱讀與理解。 示例：如下例子，排版不整齊，閱讀稍感不方便。 void example_fun( void ) { /* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two } 應改為如下布局。 void example_fun( void ) { /* code one comments */ CodeBlock One /* code two comments */ CodeBlock Two } 2-13：將注釋與其上面的代碼用空行隔開。 示例：如下例子，顯得代碼過于緊湊。 /* code one comments */ program code one /* code two comments */ program code two 應如下書寫 /* code one comments */ program code one /* code two comments */ program code two 2-14：對變量的定義和分支語句（條件分支、循環(huán)語句等）必須編寫注釋。 說明：這些語句往往是程序?qū)崿F(xiàn)某一特定功能的關鍵，對于維護人員來說，良好的注 釋幫助更好的理解程序，有時甚至優(yōu)于看設計文檔。 2- 15：對于switch語句下的case語句，如果因為特殊情況需要處理完一個case后進入下一 個case處理，必須在該case語句處理完、下一個case語句前加上明確的注釋。 說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏break語句。 示例（注意斜體加粗部分）： 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(); break; ... 2-1：避免在一行代碼或表達式的中間插入注釋。 說明：除非必要，不應在代碼或表達中間插入注釋，否則容易使代碼可理解性變差。 2- 2：通過對函數(shù)或過程、變量、結構等正確的命名以及合理地組織代碼的結構，使代碼成 為自注釋的。 說明：清晰準確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。 2-3：在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。 說明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫 助讀者理解代碼，防止沒必要的重復注釋信息。 示例：如下注釋意義不大。 /* if receive_flag is TRUE */ if (receive_flag) 而如下的注釋則給出了額外有用的信息。 /* if mtp receive a message from links */ if (receive_fla...
編程規(guī)范和范例