嵌入式系統中的C語言編碼規(guī)范

嵌入式系統中的C語言編碼標準2004-1范圍本文件規(guī)定了書寫程序代碼時的一般規(guī)那么和要求。本文件適用于研發(fā)中心監(jiān)控硬件室的嵌入式程序開發(fā)過程。原那么目的為了統一在工程開發(fā)中的程序編碼風格，提高代碼的編寫質量和可重用性，使代碼具有如下的特點：可移植性，一致性，易維護性，易理解性，整潔、簡樸和清晰。根本原那么書寫的所有C語言代碼應遵守ANSIC標準。保持代碼簡潔。語言描述直接、清晰。風格要保持一致。要防止語句復雜。慎重使用GOTO語句。及時更新舊代碼。注釋要通俗易懂，不產生歧義。源文件注意代碼行的寬度代碼行的寬度不可太長，以防止代碼在顯示器上顯示時和被打印出來后的清單不便閱讀。較長的語句要分成多行書寫，劃分出的新行要進行適當的縮進，使排版整齊，語句易讀。如果能夠做到：“長表達式在低優(yōu)先級操作符處劃分新行，操作符放在新行之首〞，就最好。關于制表符〔TAB〕因為TAB符〔ASCII碼為0x09〕在不同的計算機和打印機上所表現的可能不同，使得維護不便。要使用適宜數量的空格符〔ASCII碼為0x20〕代替TAB來對齊文字。使用4個空格的縮進方式程序塊要采用縮進風格編寫，縮進的空格數為4，縮進只使用空格鍵，不用TAB鍵。程序塊的分界符程序塊的分界符〔大括號“{〞和“}〞〕應各獨占一行并且位于同一列，同時與引用它們的語句左對齊。在函數體的開始、結構體的定義、聯合體的定義、枚舉的定義以及if、for、do、while、switch、case語句中的程序都要采用如上的縮進方式。關于文件頭和函數頭部的注釋源文件〔包括說明性如：頭文件.h文件、.inc文件、.def文件、編譯說明文件.cfg等〕頭部應放置注釋文字，注釋必須列出：版權說明、版本號、完成日期、作者、內容、模塊目的/功能、主要函數及其功能、與其它文件的關系、修改日志等，頭文件的注釋中還應有函數功能簡要說明。函數頭部也應進行注釋，注釋時要列出：函數名、函數的目的/功能、輸入參數、輸出參數、返回值、調用關系〔函數、表〕等〔必要時要舉例說明函數的使用方法〕。文件書寫的層次實現文件〔.C文件〕的層次：FileheadingRevisionhistory#include#defineconstantsMacrosLocaldatatypesLocalvariablesLocaltablesLocalfunctionprototypesGlobalfunctionsLocalfunctions聲明文件〔.H文件〕的層次：FileheadingRevisionhistory#defineconstantsGlobalmacrosGlobaldatatypesGlobalvariablesExternalsGlobalfunctionprototypes用注釋將各個主要段分隔使用如下的方式分隔：/********************************************************************************DataTypes*******************************************************************************/typedefunsignedcharBOOLEAN;/********************************************************************************Prototypes*******************************************************************************/BOOLEANTaskRdy(void);空行起著分隔程序段落的作用，空行得體〔不過多也不過少〕將使程序的布局更加清晰。必須要采取一定的措施防止頭文件被重復引用比方在使用HIWARE的HI-CROSS+編譯器時可以使用如下的方法：#ifndef_MAIN_H#define_MAIN_HBodyoftheheaderfile.#endif使用#include用#include〈filename.h〉格式來引用標準庫的頭文件〔編譯器將從標準庫目錄開始搜索〕，用#include“filename.h〞格式來引用非標準庫的頭文件〔編譯器將從用戶的工作目錄開始搜索〕。注釋原那么上使用中文注釋。使每行注釋都有其價值一般情況下，源程序有效注釋量必須在20％以上。寫注釋時要明智些！如果一段代碼的邏輯關系很復雜，注解將有助于別人理解代碼的意圖。但如果邏輯關系直線向前，防止加上并非必須的注解。注釋使用的語句要簡潔，表達要清晰、準確，不要使人產生歧義，不可喧賓奪主。分開注釋和代碼，而不要混在一起。以免閱讀代碼時注意力被分散盡可能少的在代碼語句中嵌入注釋，不要象下面的例子中的那樣。voidClkUpdateTime(void){/*DONOTcommentlikethis!*//*Updatetheseconds*/if(ClkSec>=CLK_MAX_SEC){ClkSec=0;/*Updatetheminutes*/if(ClkMin>=CLK_MAX_MIN){ClkMin=0;/*Updatethehours*/if(ClkHour>=CLK_MAX_HOURS){ClkHour=0;}else{ClkHour++;}}else{ClkMin++;}}else{ClkSec++;}}注釋要醒目，要使其易于同代碼區(qū)分出來不要象下面的例子中的那樣。/*ThistypeofcommentcanleadtoconfusionespeciallywhendescribingafunctionlikeClkUpdateTime().Thefunctionlookslikeactualcode!*/盡可能將注釋放在語句尾部，并且對齊注釋。使用適宜的方法來屏蔽暫時不執(zhí)行的代碼塊可以使用如下的方法來屏蔽暫時不執(zhí)行的代碼塊，而不要修改注釋。#if0 /*Commentsoutthefollowingcode*/#defineDISP_TBL_SIZE 5 /*Sizeofdisplaybuffertable*/#defineDISP_MAX_X 80 /*Max.numberofcharactersinXaxis*/#defineDISP_MAX_Y 25 /*Max.numberofcharactersinYaxis*/#defineDISP_MASK 0x5F#endif命名規(guī)那么總約定直觀且可以拼讀，可望文知義。標識符最好采用英文單詞或其組合，便于記憶和閱讀。切忌使用漢語拼音來命名。#defineconstants:#definemacros:typedefs:enumtags:所有的字母都用大寫形式；標識符中的各個單詞之間用下劃線分開；Examples:DISP_BUF_SIZE,MIN(),MAX(),etc.Localvariables(i.e.functionscope):所有的字母都用小寫形式；標識符中的各個單詞之間用下劃線分開；Usestandardnames(e.g.i,j,k用來作循環(huán)變量,p作指針變量等)Filescopevariables:用模塊名稱作前綴并使用下劃線與后面分開；標識符中的各個單詞之間用首字母大寫的方法來分隔開；要定義為靜態(tài)；Examples:Disp_Buf[],Comm_Ch,etc.Globalvariables:用模塊名稱作前綴；標識符中的各個單詞之間用首字母大寫的方法來分隔開；Examples:DispMapTbl[],CommErrCtr,etc.Localfunctions:用模塊名稱作前綴并使用下劃線與后面分開；標識符中的各個單詞之間用首字母大寫的方法來分隔開；要定義為靜態(tài)；Example:staticvoidComm_PutChar()Globalfunctions:用模塊名稱作前綴；標識符中的各個單詞之間用首字母大寫的方法來分隔開；Example:voidCommInit()宏和自定義的數據類型，所有的字母都用大寫形式。盡量防止局部變量與全局變量同名，如果必須同名一定要使用注釋來說明。不要出現僅靠大小寫區(qū)分的相似的標識符。用大寫首字母的方式來分開名字中的幾個詞。使用公認的縮寫〔包括國際通用和工程專用的〕經常用到的程序術語約定表可見附錄。在命名時使用“模塊名-對象-動作〞、“形容詞-名詞〞或“名詞〞的格式。關于數據類型所有的自定義數據類型都應該使用大寫字母標識符中的各個單詞之間用首字母大寫的方法來分隔開。使之便于移植可以采用如下的方法：typedefunsigned char BOOLEAN; /*Logicaldatatype(TRUEorFALSE)*/typedefunsigned char INT8U; /*Unsigned8bitvalue*/typedefsigned char INT8S; /*Signed8bitvalue*/typedefunsigned short INT16U; /*Unsigned16bitvalue*/typedefsigned short INT16S; /*Signed16bitvalue*/typedefsigned short INT32U; /*Unsigned32bitvalue*/typedefsigned short INT32S; /*Signed32bitvalue*/typedefsigned short INT64U; /*Unsigned64bitvalue(ifavailable)*/typedefsigned short INT64S; /*Signed64bitvalue(ifavailable)*/typedeffloat FP32; /*32bit,singleprec.floating-point*/typedefdouble FP64; /*64bit,doubleprec.floating-point*/數據作用范圍如果數據只在執(zhí)行文件〔.C文件〕中使用，就一定要定義在此執(zhí)行文件中。如果是全局變量，就一定要定義在頭文件〔.H文件〕中。層次每行只寫一條語句。如：DispSegTblIx=0;DispDigMsk=0x80;而不是：DispSegTblIx=0;DispDigMsk=0x80;關于空格函數參數列表中的逗號之后要有一個空格。如下所示：DispStr(x,y,s);分號之后要有一個空格。如下所示：for(i=0;i<10;i++)單目運算符在運算符與操作的對象之間不要有空格。如下所示：!value~bits++ij--(INT32U)x*ptr&xsizeof(x)雙目運算符和三目運算符，在運算符與操作的對象之間要有一個空格。如下所示：c1=c2;x+yi+=2;n>0?n:-n;a<bc>=2下面的這些操作不要加空格：操作內容舉例->結構指針p->member.成員引用s.member[]數組下標a[i]函數調用語句函數調用語句中，在函數名和圓括號之間不要放空格。如下所示：DispInit();關鍵詞在if、while、for、switch和return后跟隨著放一個空格。如下所示：if(a>b)while(x>0)for(i=0;i<10;i++)switch(x)return(y);case后的語句要縮進5個空格。如下所示：caseKEY_CR:*p=NUL;break;caseKEY_LINE_FEED:p++;break;等號相連多個用等號賦值的語句時，上下要的等號和右邊的數字或標識符要對齊。如下所示：DispSegTblIx =0;DispDigMsk =0x80;DispScale =1.25;關于圓括號在括號括住的內容與括號之間不要有空格。如下所示：x=(a+b)*c;函數一定要定義函數的返回類型，不要省略返回值的類型。在函數內局部變量定義和代碼之間空兩行。書寫時，在函數名的后面與定義函數參數的圓括號之間放一個空格。這樣可以在方便地查找函數定義，而不會受函數調用語句的影響〔在調用函數時不要放這樣的空格〕。不要在定義局部變量的同時給其賦初值，而是分成兩條語句。如果參數是指針，且僅作輸入用，那么應在類型前加const，以防止該指針在函數體內被意外修改。在函數體的“入口〞處對參數的有效性進行檢查。表達式和根本語句如果代碼中的運算符比擬多，就要使用圓括號來明確表達式的操作順序，防止使用默認的優(yōu)先級，以防止產生歧義并提高可讀性。必要編寫太復雜的復合表達式。不要有多用途的復合表達式。不可將浮點變量用“==〞或“！=〞與任何數字比擬。循環(huán)體內工作量最小化。在多重循環(huán)中，如果有可能，應當將最長的循環(huán)放在最內層，最短的循環(huán)放在最外層，以減少CPU跨切循環(huán)層的次數。如下所示：效率低：長循環(huán)在最外層效率高：長循環(huán)在最內層for(row=0;row<100;row++){for(col=0;col<5;col++){sum=sum+a[row][col];}}for(col=0;col<5;col++){for(row=0;row<100;row++){sum=sum+a[row][col];}}如果循環(huán)體內存在邏輯判斷，并且循環(huán)次數很大，宜將邏輯判斷移到循環(huán)體的外面。如下所示：效率低但程序簡潔效率高但程序不簡潔for(i=0;i<N;i++){if(condition){DoSomething();}else{DoOtherthing();}}if(condition){for(i=0;i<N;i++){DoSomething();}}else{for(i=0;i<N;i++){DoOtherthing();}}在for循環(huán)體內修改循環(huán)變量時要慎重，防止for循環(huán)失去控制。建議for語句的循環(huán)控制變量的取值采用“半開半閉區(qū)間〞寫法。對于switch語句下的每個case語句結尾，不要忘記加break。如果因為特殊情況需要處理完一個case后進入下一個case處理，必須在該case語句處理完、下一個case語句前加上明確的注釋，以防止產生誤解，誤認為漏寫“break〞。對switch語句必須有default分支。其它系統運行之初，要初始化有關變量及運行環(huán)境，防止未經初始化的變量被引用。變量的定義集中放在一起。代碼中盡量不用具體的大小數字。而是應使用宏定義代替數字，便于以后維護。與硬件相關和與編譯器、處理器有關的操作〔如：開/關中斷、驅動輸出引腳、內部定時等操作〕，建議定義成宏，便于今后維護和移植。仔細定義并明確全局變量的含義、作用、取值范圍及全局變量間的關系。