第5章 華為軟件編碼規(guī)范

1、2022年6月26日星期日1課程名稱：課程名稱：軟件工程軟件工程任課教師：任課教師：郭雷勇郭雷勇E-mail: 第第5章章 軟件編碼軟件編碼華為軟件編程規(guī)范和范例華為軟件編程規(guī)范和范例2022年6月26日星期日2華為軟件編程規(guī)范和范例-一=排版 =. 二=注釋=. 三=標識符命名=. 四=可讀性=. 五=變量、結構=. 六=函數(shù)、過程=. 七=可測性=. 八=程序效率=. 九=質(zhì)量保證=. 十=代碼編輯、編譯、審查=. 十一=代碼測試、維護=. 十二=宏=. 2022年6月26日星期日3一 = 排版 2022年6月26日星期日41-1：程序塊要采用縮進風格編寫，縮進的空格數(shù)為4個 說明：對于由

2、開發(fā)工具自動生成的代碼可以有不一致。2022年6月26日星期日51-2：相對獨立的程序塊之間、變量說明之后必須加空行示例：如下例子不符合規(guī)范。if (!valid_ni(ni) . / program coderepssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni; 應如下書寫if (!valid_ni(ni) . / program coderepssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;2022年6月26日星期日61-3

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_tableframe_id * STAT_TASK_CHECK_NUMBER + index.occupied = stat_poiindex.occupied;act_task_tabletaskno.duration_true_or_false

4、 = SYS_get_sccp_statistic_state( stat_item );report_or_not_flag = (taskno MAX_ACT_TASK_NUMBER) & (n7stat_stat_item_valid (stat_item) & (act_task_tabletaskno.result_data != 0);2022年6月26日星期日71-4：循環(huán)、判斷等語句中若有較長的表達式或語句，則要進行適應的劃分，長表達式要在低優(yōu)先級操作符處劃分新行，操作符放在新行之首if (taskno max_act_task_number) & (n

5、7stat_stat_item_valid (stat_item) . / program codefor (i = 0, j = 0; (i BufferKeywordword_index.word_length) & (j NewKeyword.word_length); i+, j+) . / program codefor (i = 0, j = 0; (i first_word_length) & (j ），后不應加空格。(1) 逗號、分號只在后面加空格。int a, b, c; (2)比較操作符, 賦值操作符=、 +=，算術操作符+、%，邏輯操作符&、&am

6、p;，位域操作符= MAX_TIME_VALUE) a = b + c;a *= 2;a = b 2; 2022年6月26日星期日15(3)!、+、-、&（地址運算符）等單目操作符前后不加空格。*p = a; / 內(nèi)容操作*與內(nèi)容之間flag = !isEmpty; / 非操作!與內(nèi)容之間p = &mem; / 地址操作& 與內(nèi)容之間i+; / +,-與內(nèi)容之間(4)-、.前后不加空格。p-id = pid; / -指針前后不加空格(5) if、for、while、switch等與后面的括號間應加空格，使if等關鍵字更為突出、明顯。if (a = b & c d

7、)注意：一行程序以小于80字符為宜，不要寫得過長。 2022年6月26日星期日16二 = 注釋 = 2022年6月26日星期日172-1：一般情況下，源程序有效注釋量必須在20以上說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準確、易懂、簡潔。2022年6月26日星期日182-2：說明性文件（如頭文件.h文件、.inc文件、.def文件、編譯說明文件.cfg等）頭部應進行注釋，注釋必須列出：版權說明、版本號、生成日期、作者、內(nèi)容、功能、與其它文件的關系、修改日志等，頭文件的注釋中還應有函數(shù)功能簡要說明示例：下面這段頭文件的頭注釋比較標準，當然

8、，并不局限于此格式，但上述信息建議要包含在內(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: / 修改歷史記錄列表，每條修改

9、記錄應包括修改日期、修改 / 者及修改內(nèi)容簡述 1. Date: Author: Modification: 2. .*/2022年6月26日星期日192-3：源文件頭部應進行注釋，列出：版權說明、版本號、生成日期、作者、模塊目的/功能、主要函數(shù)及其功能、修改日志等。示例：下面這段源文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內(nèi)。/* Copyright (C), 1988-1999, Huawei Tech. Co., Ltd. FileName: test.cpp Author: Version : Date: Description: / 模塊描述 Version

10、: / 版本信息 Function List: / 主要函數(shù)及其功能 1. - History: / 歷史修改記錄 David 96/10/12 1.0 build this moudle */說明：Description一項描述本文件的內(nèi)容、功能、內(nèi)部各部分之間的關系及本文件與其它文件關系等。History是修改歷史記錄列表，每條修改記錄應包括修改日期、修改者及修改內(nèi)容簡述。2022年6月26日星期日202-4：函數(shù)頭部應進行注釋，列出：函數(shù)的目的/功能、輸入?yún)?shù)、輸出參數(shù)、返回值、調(diào)用關系（函數(shù)、表）等示例：下面這段函數(shù)的注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內(nèi)。/*

11、 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: / 其它說明*/2022年6月26日星期日212-5：邊寫代碼邊注釋，修改代碼

12、同時修改相應的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除說明：錯誤的注釋不但無益反而有害。2-6：注釋的內(nèi)容要清楚、明了，含義準確，防止注釋二義性規(guī)則2-7：避免在注釋中使用縮寫，特別是非常用縮寫說明：在使用縮寫時或之前，應對縮寫進行必要的說明。2022年6月26日星期日222-8：注釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方（對單條語句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開示例：如下例子不符合規(guī)范。例1：repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni

13、;/* get replicate sub system index and net indicator */ 應如下書寫/* get replicate sub system index and net indicator */repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;2022年6月26日星期日232-9：對于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時都必須加以注釋，說明其物理含義。變量、常量、宏的注釋應放在其上方相鄰位置或右方示例：/* active statistic t

14、ask number */#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */2022年6月26日星期日242-10：數(shù)據(jù)結構聲明(包括數(shù)組、結構、類、枚舉等)，如果其命名不是充分自注釋的，必須加以注釋。對數(shù)據(jù)結構的注釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的注釋放在此域的右方示例：可按如下形式說明枚舉/數(shù)據(jù)/聯(lián)合結構。/* sccp interface with sccp user primitive message name */e

15、num 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 users unit data transmission request*/;2022年6月26日星期日252-11：全局變量要有較詳細的注釋，包括對其功能、取值范圍、哪些函數(shù)或過程存取它以及存取時

16、注意事項等的說明示例：/* 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 Ge

17、tGTTransErrorCode() */ / 使用方法BYTE g_GTTranErrorCode; 2022年6月26日星期日262-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

18、One /* code two comments */ CodeBlock Two2022年6月26日星期日272-13：將注釋與其上面的代碼用空行隔開示例：如下例子，顯得代碼過于緊湊。/* code one comments */program code one/* code two comments */program code two應如下書寫/* code one comments */program code one/* code two comments */program code two2022年6月26日星期日282-14：對變量的定義和分支語句（條件分支、循環(huán)語句等）必須編

19、寫注釋說明：這些語句往往是程序?qū)崿F(xiàn)某一特定功能的關鍵，對于維護人員來說，良好的注釋幫助更好的理解程序，有時甚至優(yōu)于看設計文檔。2022年6月26日星期日292-15：對于switch語句下的case語句，如果因為特殊情況需要處理完一個case后進入下一個case處理，必須在該case語句處理完、下一個case語句前加上明確的注釋說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏break語句。示例（注意斜體加粗部分）：case CMD_UP: ProcessUp(); break;case CMD_DOWN: ProcessDown(); break;case CMD_FWD: Proces

20、sFwd(); if (.) . break;else ProcessCFW_B(); / now jump into case CMD_Acase CMD_A: ProcessA(); break;case CMD_B: ProcessB(); break;case CMD_C: ProcessC(); break;case CMD_D: ProcessD(); break;.2022年6月26日星期日30說明2-1：避免在一行代碼或表達式的中間插入注釋說明：除非必要，不應在代碼或表達中間插入注釋，否則容易使代碼可理解性變差。2-2：通過對函數(shù)或過程、變量、結構等正確的命名以及合理地組織代碼

21、的結構，使代碼成為自注釋的 說明：清晰準確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。2022年6月26日星期日312-3：在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息說明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重復注釋信息。示例：如下注釋意義不大。/* if receive_flag is TRUE */if (receive_flag)而如下的注釋則給出了額外有用的信息。/* if mtp receive a message from links */if (receive_flag)2022年6月26日星

22、期日322-4：在程序塊的結束行右方加注釋標記，以表明某程序塊的結束說明：當代碼段較長，特別是多重嵌套時，這樣做可以使代碼更清晰，更便于閱讀。示例：參見如下例子。if (.) / program code while (index MAX_INDEX) / program code /* end of while (index MAX_INDEX) */ / 指明該條while語句結束 /* end of if (.)*/ / 指明是哪條if語句結束2022年6月26日星期日332-5：注釋格式盡量統(tǒng)一，建議使用“/* */”2-6：注釋應考慮程序易讀及外觀排版的因素，使用的語言若是中、英兼有

23、的，建議多使用中文，除非能用非常流利準確的英文表達說明：注釋語言不統(tǒng)一，影響程序易讀性和外觀排版，出于對維護人員的考慮，建議使用中文。2022年6月26日星期日34三 = 標識符命名 = 2022年6月26日星期日353-1：標識符的命名要清晰、明了，有明確含義，同時使用完整的單詞或大家基本可以理解的縮寫，避免使人產(chǎn)生誤解說明：較短的單詞可通過去掉“元音”形成縮寫；較長的單詞可取單詞的頭幾個字母形成縮寫；一些單詞有大家公認的縮寫。示例：如下單詞的縮寫能夠被大家基本認可。temp 可縮寫為 tmp ;flag 可縮寫為 flg ;statistic 可縮寫為 stat ;increment 可縮

24、寫為 inc ;message 可縮寫為 msg ;2022年6月26日星期日363-2：命名中若使用特殊約定或縮寫，則要有注釋說明說明：應該在源文件的開始之處，對文件中所使用的縮寫或約定，特別是特殊的縮寫，進行必要的注釋說明。2022年6月26日星期日373-3：自己特有的命名風格，要自始至終保持一致，不可來回變化說明：個人的命名風格，在符合所在項目組或產(chǎn)品組的命名規(guī)則的前提下，才可使用。（即命名規(guī)則中沒有規(guī)定到的地方才可有個人命名風格）。2022年6月26日星期日383-4：對于變量命名，禁止取單個字符（如i、j、k.），建議除了要有具體含義外，還能表明其變量類型、數(shù)據(jù)類型等，但i、j、k

25、作局部循環(huán)變量是允許的說明：變量，尤其是局部變量，如果用單個字符表示，很容易敲錯（如i寫成j），而編譯時又檢查不出來，有可能為了這個小小的錯誤而花費大量的查錯時間。示例：下面所示的局部變量名的定義方法可以借鑒。int liv_Width其變量名解釋如下： l 局部變量（Local） （其它：g 全局變量（Global）.） i 數(shù)據(jù)類型（Interger） v 變量（Variable） （其它：c 常量（Const）.） Width 變量含義這樣可以防止局部變量與全局變量重名。2022年6月26日星期日393-5：命名規(guī)范必須與所使用的系統(tǒng)風格保持一致，并在同一項目中統(tǒng)一，比如采用UNIX的全小寫加下劃線的風格或大小寫混排的方式，不要使用大小寫與下劃線混排的方式，用作特殊標識如標識成員變量或全局變量的m_和g_，其后加上大小寫混排的方式是允許的示例： Add_User不允許，add_user、AddUser、m_AddUser允許。2022年6月26日星期日40說明：3-1：除非必要，不要用數(shù)字或較奇怪的字符來定義標識符示例：如下命名，使人產(chǎn)生疑惑。#define _EXAMPLE_0_TEST_#define _EXAMPLE_