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

1、 C語言開發(fā)編碼規(guī)范軟件開發(fā)代碼規(guī)范（C）(僅通普信息技術(shù)股份有限公司供內(nèi)部使用)擬制：楊超日期：2015-3-11審核：夏峰日期：2015-3-13核準(zhǔn)：馮敬剛?cè)掌冢?015-3-17簽發(fā)：韓殿成日期：2015-4-22文檔版本：V0.11 黑龍江通普信息技術(shù)股份有限公司目錄第一章 原則5第二章 排版62.1空行62.2代碼行72.3代碼行內(nèi)的空格72.4對齊縮進(jìn)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常量命名1

2、84.6函數(shù)命名184.7枚舉命名184.8宏命名18第五章 雜項(xiàng)20第一章 原則本文檔的目的是提供一個(gè)公共的編碼規(guī)范。這個(gè)規(guī)范詳細(xì)闡述在編碼時(shí)要怎樣寫、不要怎樣寫，旨在提高代碼的可讀性、可維護(hù)性，使代碼易于管理，使所有人可以集中精力去實(shí)現(xiàn)內(nèi)容，而非處理各種復(fù)雜的表現(xiàn)形式。使代碼易于管理的方法之一是增強(qiáng)代碼一致性，讓別人可以讀懂你的代碼是很重要的，保持統(tǒng)一編程風(fēng)格意味著可以輕松根據(jù)“模式匹配”規(guī)則推斷各種符號的含義。創(chuàng)建通用的、必需的習(xí)慣用語和模式可以使代碼更加容易理解。雖然在某些情況下改變一些編程風(fēng)格可能會是好的選擇，但我們還是應(yīng)該遵循一致性原則，盡量不這樣去做。關(guān)鍵在于保持一致。第二章 排

3、版2.1 空行l(wèi) 【規(guī)則2-1-1】在每個(gè)函數(shù)、結(jié)構(gòu)體、枚舉定義結(jié)束之后都要加空行。l 【規(guī)則2-1-2】在一個(gè)函數(shù)體內(nèi)，邏輯密切相關(guān)的語句之間不加空行，其它地方應(yīng)加空行分隔。struct st1 ;/ 空行enum ;/ 空行void Function1() / 空行void Function2() / 空行while (condition)statement1;/ 空行if (condition) statement2;elsestatement3;/ 空行statement4; 函數(shù)之間的空行 函數(shù)內(nèi)部的空行l(wèi) 【規(guī)則2-1-3】相對獨(dú)立的程序塊之間、變量說明之后必須加空行。if (!i

4、s_lock_card_succ). / program codeGetLockPhoneInfo(&st_lock_phone_info);if (!is_lock_card_succ). / program code/空格GetLockPhoneInfo(&st_lock_phone_info); 不規(guī)范代碼 規(guī)范代碼2.2 代碼行l(wèi) 【規(guī)則2-2-1】一行代碼只做一件事情，如只定義一個(gè)變量，或只寫一條語句。這樣的代碼容易閱讀，并且方便于寫注釋。l 【規(guī)則2-2-2】if、for、while、do等語句自占一行，執(zhí)行語句不得緊跟其后。不論執(zhí)行語句有多少都要加。這樣可以防止書

5、寫失誤。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 < height) dosomething();if (width < height) dosomething();for (initialization; condition; update) dosomething();other();for (initialization; co

6、ndition; update)dosomething();/ 空行other();不規(guī)范代碼 規(guī)范代碼2.3 代碼行內(nèi)的空格說明：空格的目的在于更清晰的代碼。l 【規(guī)則2-3-1】關(guān)鍵字之后要留空格。const、static等關(guān)鍵字之后至少要留一個(gè)空格，否則無法辨析關(guān)鍵字；if、for、while、switch等關(guān)鍵字之后應(yīng)留一個(gè)空格再跟左括號(，以突出關(guān)鍵字。l 【規(guī)則2-3-2】函數(shù)名之后不要留空格，緊跟左括號(，以與關(guān)鍵字區(qū)別。l 【規(guī)則2-3-3】(向后緊跟，)、,、;向前緊跟，緊跟處不留空格。l 【規(guī)則2-3-4】,之后要留空格，如Function(x, y, z)。如果;不是一行

7、的結(jié)束符號，其后要留空格，如for (initialization; condition; update)。l 【規(guī)則2-3-5】賦值操作符、比較操作符、算術(shù)操作符、邏輯操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“|”、“<<”,“”等二元操作符的前后應(yīng)當(dāng)加一個(gè)空格。l 【規(guī)則2-3-6】一元操作符如“!”、“”、“+”、“-”、“&”（地址運(yùn)算符）等前后不加空格。l 【規(guī)則2-3-7】象“”、“.”、“->”這類操作符前后不加空格。l 【建議2-3-1】對于表達(dá)式比較長的for語句和if

8、語句，為了緊湊起見可以適當(dāng)?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 >= 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

9、+)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->Function();array 5 = 0;a . Function();b -> Function();良好風(fēng)格 不良風(fēng)格2.4 對齊縮進(jìn)l 【規(guī)則2-4-1】程序塊要采用縮進(jìn)風(fēng)格編寫。l 【規(guī)則2-4-2】對齊使用TAB鍵，TAB鍵寬度設(shè)置為4個(gè)空格。說明：應(yīng)注意使用不同編輯器時(shí)，TAB鍵

10、設(shè)置不同造成的排版不同；應(yīng)注意某些編輯器在識別、顯示TAB鍵上存在問題；最終排版應(yīng)以在項(xiàng)目的主代碼編輯器（如VC、Source Insight等）中顯示一致統(tǒng)一、整潔清晰為準(zhǔn)。Source Insight中設(shè)置：Options->Doucument Options->“Tab Width:4”l 【規(guī)則2-4-3】函數(shù)或過程的開始、結(jié)構(gòu)的定義及循環(huán)、判斷等語句中的代碼都要采用縮進(jìn)風(fēng)格，case語句下的情況處理語句也要遵從語句縮進(jìn)要求。l 【規(guī)則2-4-4】程序塊的分界符（如和）應(yīng)各獨(dú)占一行并且位于同一列，同時(shí)與引用它們的語句左對齊。在函數(shù)體的開始、類的定義、結(jié)構(gòu)的定義、枚舉的定義以

11、及if、for、do、while、switch、case語句中的程序都要采用如上的縮進(jìn)方式。for (.) . / program codefor (.) . / program codeif (.) . / program code if (.) . / program codevoid example_fun( void ) . / program code void example_fun( void ) . / program code不規(guī)范代碼 規(guī)范代碼l 【規(guī)則2-4-5】預(yù)處理指令不需要縮進(jìn)，總是從行首開始。即使預(yù)處理指令位于縮進(jìn)代碼塊中，指令也應(yīng)從行首開始。/ 良好風(fēng)格：預(yù)處理

12、指令均從行首開始 if (lopsided_score) #if DISASTER_PENDING / Correct - Starts at beginning of line DropEverything();#if NOTIFY NotifyClient();#endif#endif BackToNormal(); / 不良風(fēng)格：縮進(jìn)的預(yù)處理指令 if (lopsided_score) #if DISASTER_PENDING / Wrong! The "#if" should be at beginning of line DropEverything(); #en

13、dif / Wrong! Do not indent "#endif" BackToNormal(); 2.5 長行拆分l 【規(guī)則2-5-1】代碼行最大長度宜控制在100至110個(gè)字符以內(nèi)。代碼行不要過長，否則眼睛看不過來，也不便于打印。l 【規(guī)則2-5-2】較長的語句（>110字符）要分成多行書寫；長表達(dá)式要在低優(yōu)先級操作符處拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要進(jìn)行適當(dāng)?shù)目s進(jìn)，使排版整齊，語句可讀。l 【規(guī)則2-5-3】循環(huán)、判斷等語句中若有較長的表達(dá)式或語句，則要進(jìn)行適應(yīng)的劃分. 長表達(dá)式要在低優(yōu)先級操作符處劃分新行，操作符放在新行之首

14、。l 【規(guī)則2-5-4】若函數(shù)或過程中的參數(shù)較長，則要進(jìn)行適當(dāng)?shù)膭澐?。if (very_longer_variable1 >= very_longer_variable12)&& (very_longer_variable3 <= very_longer_variable14)&& (very_longer_variable5 <= very_longer_variable16) dosomething();virtual CMatrix CMultiplyMatrix (CMatrix leftMatrix, CMatrix rightMat

15、rix);for (very_longer_initialization; very_longer_condition; very_longer_update)dosomething();report_or_not_flag = (taskno < MAX_ACT_TASK_NUMBER) && (n7stat_stat_item_valid (stat_item) && (act_task_tabletaskno.result_data != 0);n7stat_str_compare(BYTE *) & stat_object, (BYTE *

16、) & (act_task_tabletaskno.stat_object), sizeof (_STAT_OBJECT);長行的拆分第三章 注釋3.1 通用規(guī)則l 【規(guī)則3-1-1】一般情況，需要保證程序有一定的注釋。必須保證關(guān)鍵的函數(shù)、流程、類型定義、變量等有相應(yīng)注釋說明。說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準(zhǔn)確、易懂、。l 【規(guī)則3-1-2】注釋應(yīng)當(dāng)準(zhǔn)確、易懂，防止注釋有二義性。說明：錯(cuò)誤的注釋不但無益反而有害。l 【規(guī)則3-1-3】除非能使用準(zhǔn)確的英文表達(dá)，則使用中文注釋。l 【規(guī)則3-1-4】避免在注釋中使用縮寫，

17、特別是非常用縮寫。說明：在使用縮寫時(shí)或之前，應(yīng)對縮寫進(jìn)行必要的說明。l 【規(guī)則3-1-5】需要為代碼中使用的縮寫增加注釋,文件引入的新縮寫必須在文件頭部加以說明。l 【規(guī)則3-1-6】通過對函數(shù)或過程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的。說明：清晰準(zhǔn)確的函數(shù)、變量等的命名，可增加代碼可讀性，并減少不必要的注釋。l 【規(guī)則3-1-7】注釋格式盡量統(tǒng)一。建議使用/進(jìn)行注釋，多行注釋可使用“/* */”。3.2 文件注釋l 【規(guī)則3-2】源文件（包含.h頭文件、.c源文件及各種腳本文件等）頭部應(yīng)進(jìn)行注釋，應(yīng)列出：版權(quán)說明、文件名、文件目的/功能，作者、創(chuàng)建日期等；如果

18、源文件引入了新的縮寫，則必須在文件頭部注釋說明。文件注釋格式定義如下（可以不局限于該格式中定義的內(nèi)容，但必須包含該格式中定義的內(nèi)容）：/* Copyright (C) 2010-2011, XXX Co. Ltd.* All rights reserved.* FileName: / 文件名稱* Description: / 文件描述* Author: / 作者* Date: / 創(chuàng)建時(shí)間* Others: / 其它說明*/* Abbreviation: / 如果文件引入了新的縮寫，則必須在此處加以說明*/舉例如下：/* Copyright (C) 2010-2011, XXX Co. Ltd

19、.* All rights reserved.* FileName: starlib_nvset.h* Description: NV參數(shù)配置源文件* Author: zc* Date: 2010/4/13* Others: */*Abbreviation:NCM: Net Choose Menu 網(wǎng)絡(luò)選擇菜單VBC: Voice Broadcast 語音播報(bào) */3.3 函數(shù)注釋l 【規(guī)則3-3】函數(shù)頭部應(yīng)進(jìn)行注釋，需要列出函數(shù)的功能、參數(shù)、返回值等。函數(shù)注釋格式定義如下（可以不局限于該格式中定義的內(nèi)容，但必須包含該格式中定義的內(nèi)容）：/*/ Function: / 函數(shù)名稱/ Descri

20、ption: / 函數(shù)功能描述/ Param: / 參數(shù)說明，包括參數(shù)的作用、取值范圍等，格式如下：/ param1: 輸入輸出類型IN/OUT/INOUT 說明/ param2: 輸入輸出類型IN/OUT/INOUT 說明/ / Return: / 函數(shù)返回值說明/ Others: / 其它說明/ Author: / 作者/*/舉例如下：/*/ Function: StarLib_SetIdleNetIconType/ Description: 設(shè)置待機(jī)界面網(wǎng)絡(luò)圖標(biāo)/ PARAM: icon:IN待機(jī)界面網(wǎng)絡(luò)圖標(biāo)/ Return: 設(shè)置成功 = STARLIB_TRUE/ 設(shè)置失敗 = ST

21、ARLIB_FALSE/ Others: / Author: zc/*/3.4 數(shù)據(jù)注釋l 【規(guī)則3-4-1】對于所有有物理含義的變量、常量，如果其命名不是充分自注釋的，在聲明時(shí)都必須加以注釋，說明其物理含義。變量、常量、宏的注釋應(yīng)放在其上方相鄰位置或右方。/ active statistic task number#define MAX_ACT_TASK_NUMBER 1000#define MAX_ACT_TASK_NUMBER 1000 / active statistic task numberl 【規(guī)則3-4-2】數(shù)據(jù)結(jié)構(gòu)聲明(包括結(jié)構(gòu)體、枚舉、類等)，如果其命名不是充分自注釋的，必

22、須加以注釋。對數(shù)據(jù)結(jié)構(gòu)的注釋應(yīng)放在其上方相鄰位置；對結(jié)構(gòu)中每個(gè)域的注釋放在該域的右方。/ 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 u

23、nit data transmission request;l 【規(guī)則3-4-3】全局變量必須有注釋，包括對其功能、取值、及其他注意事項(xiàng)等的說明。/標(biāo)志是否通過鎖卡流程；TURE = 通過鎖卡流程，F(xiàn)ALSE = 鎖卡流程失敗PUBLIC BOOLEAN g_isLockCardPass = FALSE;3.5 代碼注釋l 【規(guī)則3-5-1】邊寫代碼邊注釋，修改代碼同時(shí)修改相應(yīng)的注釋，以保證注釋與代碼的一致性。不再有用的注釋要?jiǎng)h除！l 【規(guī)則3-5-2】如果代碼本來就是清楚的，則不必加注釋。i+; / i 加 1，多余的注釋 l 【規(guī)則3-5-3】在代碼的功能、意圖層次上進(jìn)行注釋，提供有用、額

24、外的信息。/ if receive_flag is TRUEif (receive_flag)/ if mtp receive a message from linksif (receive_flag) 無用注釋 有用注釋l 【規(guī)則3-5-4】注釋應(yīng)與其描述的代碼相鄰。對語句塊的注釋必須放在語句塊上方；對單條語句、變量定義的注釋可以放在上方或右方（建議放在右方）；注釋不可放在下方。/get replicate sub system index and net indicator repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_da

25、taindex.ni;不良寫法一repssn_ind = ssn_dataindex.repssn_index;repssn_ni = ssn_dataindex.ni;/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;良好的寫法l 【規(guī)則3-5-5】如果注釋放在上方，則將注釋與其上面的代碼用空行隔

26、開。/ code one comments program code one/ code two comments program code two/code one comments program code one / code two commentsprogram code two 過于緊湊 良好寫法l 【規(guī)則3-5-6】避免在一行代碼或表達(dá)式的中間插入注釋。說明：除非必要，不應(yīng)在代碼或表達(dá)中間插入注釋，否則容易使代碼可理解性變差。l 【規(guī)則3-5-7】對于switch語句下的case語句，如果因?yàn)樘厥馇闆r需要處理完一個(gè)case后進(jìn)入下一個(gè)case處理，必須在該case語句處理完、下一

27、個(gè)case語句前加上明確的注釋。說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏break語句。case CMD_A: ProcessA(); break;case CMD_B: ProcessB (); / 跳轉(zhuǎn)到case CMD_Ccase CMD_C: ProcessC(); break;l 【規(guī)則3-5-8】注釋與所描述內(nèi)容進(jìn)行同樣的縮排。說明：可使程序排版整齊，并方便注釋的閱讀與理解。void example_fun( void )/code one comments CodeBlock One /code two comments CodeBlock Twovoid examp

28、le_fun( void ) / code one comments CodeBlock One / code two comments CodeBlock Two 不好的注釋縮排 良好的注釋縮排第四章 命名4.1 通用命名規(guī)則l 【規(guī)則4-1-1】標(biāo)識符的命名要清晰明了，有明確含義；命名應(yīng)具有描述性；一般而言，類型和變量應(yīng)是名詞，函數(shù)應(yīng)是“命令性”動詞； int counter; /計(jì)數(shù)器名詞NET_ICON_TYPE icon_type; / NET_ICON_TYPE 網(wǎng)絡(luò)圖標(biāo)類型名詞/設(shè)置IDLE頁面網(wǎng)絡(luò)圖標(biāo)類型“命令性”動詞NET_ICON_TYPE StarLib_GetIdleN

29、etIconType(); l 【規(guī)則4-1-2】命名應(yīng)使用使用完整的單詞或大家可以理解的縮寫，避免使人產(chǎn)生誤解；如使用特殊約定或縮寫，要有注釋說明，可參見【規(guī)則3-3】；需注意避免過度縮寫。/良好命名int num_error; int num_connections;NET_TYPE StarLib_GetNetWorkType();/過度縮寫int nerr; int n_conns;NET_TYPE StarLib_GetNWType();4.2 文件命名l 【規(guī)則4-2】文件名全部小寫；為避免由于文件名過長造成難以理解，可以在適當(dāng)位置使用下劃線進(jìn)行分隔。不良的文件命名：mmieven

30、tmanager.h（過長難以理解） Star_HttpServer.h（含大寫字母）良好的文件命名：starlib_nv.h mmi_applet_table.h mmicc_speeddial.c4.3 類型命名l 【規(guī)則4-3-1】結(jié)構(gòu)體（struct）類型名遵循如下規(guī)則：每個(gè)單詞首字母大寫，單詞間使用下劃線相連，以_struct后綴結(jié)束；命名中的前綴、關(guān)鍵縮寫詞等可以適當(dāng)?shù)牟扇∪看髮?。struct的typedef類型定義名遵循如下規(guī)則：和struct名采用相同命名，但全部字母大寫，單詞間使用下劃線相連，并以_T后綴結(jié)束。一般而言，struct需同時(shí)定義類型名和typedef名。typ

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

32、_TEL_TYPE_E;l 【規(guī)則4-3-3】函數(shù)指針（pointer to function）的typdef名遵循如下規(guī)則：單詞全部字母大寫，單詞間使用下劃線相連，以_PFUNC后綴結(jié)束。typedef void (*AUDIO_NOTIFY_CALLBACK_PFUNC)(HAUDIO hAudio, uint32 notify_info, uint32 affix_info);4.4 變量命名l 【規(guī)則4-4-1】包括局部變量、全局變量、參數(shù)變量、成員變量，變量名一律小寫，單詞間使用下劃線相連；命名中的前綴、關(guān)鍵縮寫詞等可以適當(dāng)?shù)牟扇∪看髮?。不良的命名：char * strTable;

33、 /大小寫混雜，放棄使用該種命名方式良好的命名：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_前綴，普通全局變量使用g_前綴。ATC_INFO_T g_atc_info_table10; /普通全局變量static BOOLEAN s_battery_status; /靜態(tài)全局變量l 【規(guī)則4-4-3】對于變量命名，禁止使用單個(gè)字符（如i、j、k等）。i、j、k等僅能用作局部循環(huán)變量

34、。單個(gè)字母唯一可使用的場合：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ù)名中每個(gè)單詞首字母大寫；為避免由于函數(shù)名過長造成難以理解，可以在適當(dāng)位置使用下劃線進(jìn)行分隔；命名中的前綴、關(guān)鍵縮寫詞等可以適當(dāng)?shù)牟扇∪看髮?。不良的命名：charge_init(); /未采用正確的大小寫規(guī)則MMIAPICCProcessVideoCallPhoneNumExt(); /函數(shù)名太長且沒有分隔，造成理解困難良好命名：Charge_Init();MMIAPICC_ProcessVideoCallPhoneNumExt