軟件開發(fā)代碼規(guī)范(C語言)

1、 XX產(chǎn)品研究部文 檔 編 號產(chǎn)品版本密級開發(fā)適用共 頁收文：XX產(chǎn)品研究部軟件開發(fā)人員 軟件開發(fā)代碼規(guī)范(僅供內(nèi)部使用)擬制：周超日期：2011-5-11審核：日期：核準：日期：簽發(fā)：日期：文檔版本：V0.11目錄第一章 原則5第二章 排版62.1空行62.2代碼行72.3代碼行內(nèi)的空格72.4對齊縮進82.5長行拆分9第三章 注釋113.1通用規(guī)則113.2文件注釋113.3函數(shù)注釋123.4數(shù)據(jù)注釋133.5代碼注釋13第四章 命名164.1通用命名規(guī)則164.2文件命名164.3類型命名164.4變量命名174.5常量命名184.6函數(shù)命名184.7枚舉命名184.8宏命名18第五章

2、雜項20文件修改記錄修改日期版本修改頁碼、章節(jié)、條款修改描述作者2011-4-290.1創(chuàng)建初稿周超2011-5-110.113.3數(shù)據(jù)注釋4.3類型命名4.4變量命名4.6函數(shù)命名1）修改3.4數(shù)據(jù)注釋【規(guī)則3-4-3】全局變量注釋例子2）在“4.3類型命名”、“4.4變量命名”、“4.6函數(shù)命名”中，增加對前綴、關鍵縮寫詞等可以適當全部大寫的處理。周超第一章 原則本文檔的目的是提供一個公共的編碼規(guī)范。這個規(guī)范詳細闡述在編碼時要怎樣寫、不要怎樣寫，旨在提高代碼的可讀性、可維護性，使代碼易于管理，使所有人可以集中精力去實現(xiàn)內(nèi)容，而非處理各種復雜的表現(xiàn)形式。使代碼易于管理的方法之一是增強代碼一致

3、性，讓別人可以讀懂你的代碼是很重要的，保持統(tǒng)一編程風格意味著可以輕松根據(jù)“模式匹配”規(guī)則推斷各種符號的含義。創(chuàng)建通用的、必需的習慣用語和模式可以使代碼更加容易理解。雖然在某些情況下改變一些編程風格可能會是好的選擇，但我們還是應該遵循一致性原則，盡量不這樣去做。關鍵在于保持一致。第二章 排版2.1 空行l(wèi) 【規(guī)則2-1-1】在每個函數(shù)、結構體、枚舉定義結束之后都要加空行。l 【規(guī)則2-1-2】在一個函數(shù)體內(nèi)，邏輯密切相關的語句之間不加空行，其它地方應加空行分隔。struct st1 ;/ 空行enum ;/ 空行void Function1() / 空行void Function2() / 空行

4、while (condition)statement1;/ 空行if (condition) statement2;elsestatement3;/ 空行statement4; 函數(shù)之間的空行 函數(shù)內(nèi)部的空行l(wèi) 【規(guī)則2-1-3】相對獨立的程序塊之間、變量說明之后必須加空行。if (!is_lock_card_succ). / program codeGetLockPhoneInfo(&st_lock_phone_info);if (!is_lock_card_succ). / program code/空格GetLockPhoneInfo(&st_lock_phone_inf

5、o); 不規(guī)范代碼 規(guī)范代碼2.2 代碼行l(wèi) 【規(guī)則2-2-1】一行代碼只做一件事情，如只定義一個變量，或只寫一條語句。這樣的代碼容易閱讀，并且方便于寫注釋。l 【規(guī)則2-2-2】if、for、while、do等語句自占一行，執(zhí)行語句不得緊跟其后。不論執(zhí)行語句有多少都要加。這樣可以防止書寫失誤。int width, height, depth;/ 寬度高度深度int width; / 寬度int height;/ 高度int depth;/ 深度X a + b; y = c + d; z = e + f;x = a + b;y = c + d;z = e + f;if (width <

6、height) dosomething();if (width < height) dosomething();for (initialization; condition; update) dosomething();other();for (initialization; condition; update)dosomething();/ 空行other();不規(guī)范代碼 規(guī)范代碼2.3 代碼行內(nèi)的空格說明：空格的目的在于更清晰的代碼。l 【規(guī)則2-3-1】關鍵字之后要留空格。const、static等關鍵字之后至少要留一個空格，否則無法辨析關鍵字；if、for、while、switc

7、h等關鍵字之后應留一個空格再跟左括號(，以突出關鍵字。l 【規(guī)則2-3-2】函數(shù)名之后不要留空格，緊跟左括號(，以與關鍵字區(qū)別。l 【規(guī)則2-3-3】(向后緊跟，)、,、;向前緊跟，緊跟處不留空格。l 【規(guī)則2-3-4】,之后要留空格，如Function(x, y, z)。如果;不是一行的結束符號，其后要留空格，如for (initialization; condition; update)。l 【規(guī)則2-3-5】賦值操作符、比較操作符、算術操作符、邏輯操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“|”、“<&

8、lt;”,“”等二元操作符的前后應當加一個空格。l 【規(guī)則2-3-6】一元操作符如“!”、“”、“+”、“-”、“&”（地址運算符）等前后不加空格。l 【規(guī)則2-3-7】象“”、“.”、“->”這類操作符前后不加空格。l 【建議2-3-1】對于表達式比較長的for語句和if語句，為了緊湊起見可以適當?shù)厝サ粢恍┛崭?，如for (i=0; i<10; i+)和if (a<=b) && (c<=d)void Func1(int x, int y, int z);void Func1 (int x,int y,int z);if (year >=

9、2000)if(year>=2000)if (a>=b) && (c<=d)if (a >= b) && (c <= d)if(a>=b&&c<=d)for (i = 0; i < 10; i+)for (i=0; i<10; i+)for(i=0;i<10;i+)x = a < b ? a : b;x=a<b?a:b;i+;int *x = &y;i +;int * x = & y; array5 = 0;a.Function();b->Functio

10、n();array 5 = 0;a . Function();b -> Function();良好風格 不良風格2.4 對齊縮進l 【規(guī)則2-4-1】程序塊要采用縮進風格編寫。l 【規(guī)則2-4-2】對齊使用TAB鍵，TAB鍵寬度設置為4個空格。說明：應注意使用不同編輯器時，TAB鍵設置不同造成的排版不同；應注意某些編輯器在識別、顯示TAB鍵上存在問題；最終排版應以在項目的主代碼編輯器（如VC、Source Insight等）中顯示一致統(tǒng)一、整潔清晰為準。Source Insight中設置：Options->Doucument Options->“Tab Width:4”l 【

11、規(guī)則2-4-3】函數(shù)或過程的開始、結構的定義及循環(huán)、判斷等語句中的代碼都要采用縮進風格，case語句下的情況處理語句也要遵從語句縮進要求。l 【規(guī)則2-4-4】程序塊的分界符（如和）應各獨占一行并且位于同一列，同時與引用它們的語句左對齊。在函數(shù)體的開始、類的定義、結構的定義、枚舉的定義以及if、for、do、while、switch、case語句中的程序都要采用如上的縮進方式。for (.) . / program codefor (.) . / program codeif (.) . / program code if (.) . / program codevoid example_fu

12、n( void ) . / program code void example_fun( void ) . / program code不規(guī)范代碼 規(guī)范代碼l 【規(guī)則2-4-5】預處理指令不需要縮進，總是從行首開始。即使預處理指令位于縮進代碼塊中，指令也應從行首開始。/ 良好風格：預處理指令均從行首開始 if (lopsided_score) #if DISASTER_PENDING / Correct - Starts at beginning of line DropEverything();#if NOTIFY NotifyClient();#endif#endif BackToNorm

13、al(); / 不良風格：縮進的預處理指令 if (lopsided_score) #if DISASTER_PENDING / Wrong! The "#if" should be at beginning of line DropEverything(); #endif / Wrong! Do not indent "#endif" BackToNormal(); 2.5 長行拆分l 【規(guī)則2-5-1】代碼行最大長度宜控制在100至110個字符以內(nèi)。代碼行不要過長，否則眼睛看不過來，也不便于打印。l 【規(guī)則2-5-2】較長的語句（>110字符）

14、要分成多行書寫；長表達式要在低優(yōu)先級操作符處拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要進行適當?shù)目s進，使排版整齊，語句可讀。l 【規(guī)則2-5-3】循環(huán)、判斷等語句中若有較長的表達式或語句，則要進行適應的劃分. 長表達式要在低優(yōu)先級操作符處劃分新行，操作符放在新行之首。l 【規(guī)則2-5-4】若函數(shù)或過程中的參數(shù)較長，則要進行適當?shù)膭澐?。if (very_longer_variable1 >= very_longer_variable12)&& (very_longer_variable3 <= very_longer_variable14)&am

15、p;& (very_longer_variable5 <= very_longer_variable16) dosomething();virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix, CMatrix rightMatrix);for (very_longer_initialization; very_longer_condition; very_longer_update)dosomething();report_or_not_flag = (taskno < MAX_ACT_TASK_NUMBER) &&a

16、mp; (n7stat_stat_item_valid (stat_item) && (act_task_tabletaskno.result_data != 0);n7stat_str_compare(BYTE *) & stat_object, (BYTE *) & (act_task_tabletaskno.stat_object), sizeof (_STAT_OBJECT);長行的拆分第三章 注釋3.1 通用規(guī)則l 【規(guī)則3-1-1】一般情況，需要保證程序有一定的注釋。必須保證關鍵的函數(shù)、流程、類型定義、變量等有相應注釋說明。說明：注釋的原則是有助于對

17、程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準確、易懂、。l 【規(guī)則3-1-2】注釋應當準確、易懂，防止注釋有二義性。說明：錯誤的注釋不但無益反而有害。l 【規(guī)則3-1-3】除非能使用準確的英文表達，則使用中文注釋。l 【規(guī)則3-1-4】避免在注釋中使用縮寫，特別是非常用縮寫。說明：在使用縮寫時或之前，應對縮寫進行必要的說明。l 【規(guī)則3-1-5】需要為代碼中使用的縮寫增加注釋,文件引入的新縮寫必須在文件頭部加以說明。l 【規(guī)則3-1-6】通過對函數(shù)或過程、變量、結構等正確的命名以及合理地組織代碼的結構，使代碼成為自注釋的。說明：清晰準確的函數(shù)、變量等的命名，可增加

18、代碼可讀性，并減少不必要的注釋。l 【規(guī)則3-1-7】注釋格式盡量統(tǒng)一。建議使用/進行注釋，多行注釋可使用“/* */”。3.2 文件注釋l 【規(guī)則3-2】源文件（包含.h頭文件、.c源文件及各種腳本文件等）頭部應進行注釋，應列出：版權說明、文件名、文件目的/功能，作者、創(chuàng)建日期等；如果源文件引入了新的縮寫，則必須在文件頭部注釋說明。文件注釋格式定義如下（可以不局限于該格式中定義的內(nèi)容，但必須包含該格式中定義的內(nèi)容）：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: / 文件名稱* Descrip

19、tion: / 文件描述* Author: / 作者* Date: / 創(chuàng)建時間* Others: / 其它說明*/* Abbreviation: / 如果文件引入了新的縮寫，則必須在此處加以說明*/舉例如下：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: starlib_nvset.h* Description: NV參數(shù)配置源文件* Author: zc* Date: 2010/4/13* Others: */*Abbreviation:NCM: Net Choose Menu 網(wǎng)絡選擇菜單

20、VBC: Voice Broadcast 語音播報 */3.3 函數(shù)注釋l 【規(guī)則3-3】函數(shù)頭部應進行注釋，需要列出函數(shù)的功能、參數(shù)、返回值等。函數(shù)注釋格式定義如下（可以不局限于該格式中定義的內(nèi)容，但必須包含該格式中定義的內(nèi)容）：/*/ Function: / 函數(shù)名稱/ Description: / 函數(shù)功能描述/ Param: / 參數(shù)說明，包括參數(shù)的作用、取值范圍等，格式如下：/ param1: 輸入輸出類型IN/OUT/INOUT 說明/ param2: 輸入輸出類型IN/OUT/INOUT 說明/ / Return: / 函數(shù)返回值說明/ Others: / 其它說明/ Autho

21、r: / 作者/*/舉例如下：/*/ Function: StarLib_SetIdleNetIconType/ Description: 設置待機界面網(wǎng)絡圖標/ PARAM: icon:IN待機界面網(wǎng)絡圖標/ Return: 設置成功 = STARLIB_TRUE/ 設置失敗 = STARLIB_FALSE/ Others: / Author: zc/*/3.4 數(shù)據(jù)注釋l 【規(guī)則3-4-1】對于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時都必須加以注釋，說明其物理含義。變量、常量、宏的注釋應放在其上方相鄰位置或右方。/ active statistic task num

22、ber#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 / active statistic task numberl 【規(guī)則3-4-2】數(shù)據(jù)結構聲明(包括結構體、枚舉、類等)，如果其命名不是充分自注釋的，必須加以注釋。對數(shù)據(jù)結構的注釋應放在其上方相鄰位置；對結構中每個域的注釋放在該域的右方。/ sccp interface with sccp user primitive message name enum SCCP_USER_PRIMITIVE N_UNITDATA_IND, / sccp notify scc

23、p 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;l 【規(guī)則3-4-3】全局變量必須有注釋，包括對其功能、取值、及其他注意事項等的說明。/標志是否通過鎖卡流程；TURE = 通過鎖卡流程，F(xiàn)ALSE = 鎖卡流程失敗PUBLIC BOOLEAN g_isLockCardPass = FALSE;3.5

24、 代碼注釋l 【規(guī)則3-5-1】邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除！l 【規(guī)則3-5-2】如果代碼本來就是清楚的，則不必加注釋。i+; / i 加 1，多余的注釋 l 【規(guī)則3-5-3】在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。/ if receive_flag is TRUEif (receive_flag)/ if mtp receive a message from linksif (receive_flag) 無用注釋 有用注釋l 【規(guī)則3-5-4】注釋應與其描述的代碼相鄰。對語句塊的注釋必須放在語句塊上方；對單條語

25、句、變量定義的注釋可以放在上方或右方（建議放在右方）；注釋不可放在下方。/get replicate sub system index and net indicator repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;不良寫法一repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;/get replicate sub system index and net indicator 不良寫法二/ get replicate

26、sub system index and net indicator repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;良好的寫法l 【規(guī)則3-5-5】如果注釋放在上方，則將注釋與其上面的代碼用空行隔開。/ code one comments program code one/ code two comments program code two/code one comments program code one / code two commentsprogram code two 過于緊湊 良好寫法l

27、 【規(guī)則3-5-6】避免在一行代碼或表達式的中間插入注釋。說明：除非必要，不應在代碼或表達中間插入注釋，否則容易使代碼可理解性變差。l 【規(guī)則3-5-7】對于switch語句下的case語句，如果因為特殊情況需要處理完一個case后進入下一個case處理，必須在該case語句處理完、下一個case語句前加上明確的注釋。說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏break語句。case CMD_A: ProcessA(); break;case CMD_B: ProcessB (); / 跳轉(zhuǎn)到case CMD_Ccase CMD_C: ProcessC(); break;l 【規(guī)則3

28、-5-8】注釋與所描述內(nèi)容進行同樣的縮排。說明：可使程序排版整齊，并方便注釋的閱讀與理解。void example_fun( void )/code one comments CodeBlock One /code two comments CodeBlock Twovoid example_fun( void ) / code one comments CodeBlock One / code two comments CodeBlock Two 不好的注釋縮排 良好的注釋縮排第四章 命名4.1 通用命名規(guī)則l 【規(guī)則4-1-1】標識符的命名要清晰明了，有明確含義；命名應具有描述性；一般而言

29、，類型和變量應是名詞，函數(shù)應是“命令性”動詞； int counter; /計數(shù)器名詞NET_ICON_TYPE icon_type; / NET_ICON_TYPE 網(wǎng)絡圖標類型名詞/設置IDLE頁面網(wǎng)絡圖標類型“命令性”動詞NET_ICON_TYPE StarLib_GetIdleNetIconType(); l 【規(guī)則4-1-2】命名應使用使用完整的單詞或大家可以理解的縮寫，避免使人產(chǎn)生誤解；如使用特殊約定或縮寫，要有注釋說明，可參見【規(guī)則3-3】；需注意避免過度縮寫。/良好命名int num_error; int num_connections;NET_TYPE StarLib_Get

30、NetWorkType();/過度縮寫int nerr; int n_conns;NET_TYPE StarLib_GetNWType();4.2 文件命名l 【規(guī)則4-2】文件名全部小寫；為避免由于文件名過長造成難以理解，可以在適當位置使用下劃線進行分隔。不良的文件命名：mmieventmanager.h（過長難以理解） Star_HttpServer.h（含大寫字母）良好的文件命名：starlib_nv.h mmi_applet_table.h mmicc_speeddial.c4.3 類型命名l 【規(guī)則4-3-1】結構體（struct）類型名遵循如下規(guī)則：每個單詞首字母大寫，單詞間使用下

31、劃線相連，以_struct后綴結束；命名中的前綴、關鍵縮寫詞等可以適當?shù)牟扇∪看髮?。struct的typedef類型定義名遵循如下規(guī)則：和struct名采用相同命名，但全部字母大寫，單詞間使用下劃線相連，并以_T后綴結束。一般而言，struct需同時定義類型名和typedef名。typedef struct AUDIO_Codec_Ext_CfgInfo_struct /AUDIO為前綴，采取全部大寫 AUDIO_CODEC_EXT_CFGINFO_T;l 【規(guī)則4-3-2】枚舉（enum）類型名遵循如下規(guī)則：每個單詞首字母大寫，單詞間使用下劃線相連，以_enum后綴結束；命名中的前綴、關鍵

32、縮寫詞等可以適當?shù)牟扇∪看髮?。enum的typedef類型定義名遵循如下規(guī)則：和enum名采用相同命名，但全部字母大寫，單詞間使用下劃線相連，并以_E后綴結束。一般，enum無需定義類型名，僅需定義typedef名。typedef enum Star_Tel_Type_EnumSTAR_TEL_TYPE_E;l 【規(guī)則4-3-3】函數(shù)指針（pointer to function）的typdef名遵循如下規(guī)則：單詞全部字母大寫，單詞間使用下劃線相連，以_PFUNC后綴結束。typedef void (*AUDIO_NOTIFY_CALLBACK_PFUNC)(HAUDIO hAudio, ui

33、nt32 notify_info, uint32 affix_info);4.4 變量命名l 【規(guī)則4-4-1】包括局部變量、全局變量、參數(shù)變量、成員變量，變量名一律小寫，單詞間使用下劃線相連；命名中的前綴、關鍵縮寫詞等可以適當?shù)牟扇∪看髮?。不良的命名：char * strTable; /大小寫混雜，放棄使用該種命名方式良好的命名：AW_LCD_PARAM_T lcd_param;char nv_phone_num10;void StarLib_GetKeyRingInfo(U8 * key_type_ptr,U8 * key_vol_ptr);l 【規(guī)則4-4-2】靜態(tài)全局變量使用s_前綴

34、，普通全局變量使用g_前綴。ATC_INFO_T g_atc_info_table10; /普通全局變量static BOOLEAN s_battery_status; /靜態(tài)全局變量l 【規(guī)則4-4-3】對于變量命名，禁止使用單個字符（如i、j、k等）。i、j、k等僅能用作局部循環(huán)變量。單個字母唯一可使用的場合：for (i = 0; i < max; i+)4.5 常量命名l 【規(guī)則4-5-1】常量名全部字母大寫。const float PI = 3.14;const int VAL_MIN = 1;4.6 函數(shù)命名l 【規(guī)則4-6-1】函數(shù)名中每個單詞首字母大寫；為避免由于函數(shù)名過長造成難以理解，可以在適當位置使用下劃線進行分隔；命名中的前綴、關鍵縮寫詞等可以適當?shù)牟扇∪看髮?。不良的命名：charge_init(); /未采用正確的大小寫規(guī)則MMIAPICCProcessVideoCallPhoneNumExt(); /函數(shù)名太長且沒有分隔，造成理解困難良好命名：Charge_Init();MMIAPICC_ProcessVideoC