嵌入式軟件編程開(kāi)發(fā)規范及原則

　　不知道大家有沒(méi)有這樣的感受：看到不規范(雜亂差)的代碼，瞬間就沒(méi)有看下去的欲望了。

　　相信大家看到標題都應該能明白編程的規范及原則對于每一個(gè)軟件開(kāi)發(fā)的工程師來(lái)說(shuō)是多么重要。

　　初學(xué)者編寫(xiě)測試程序、小的模塊程序也許不能感受它的重要性;但有經(jīng)驗及大型項目開(kāi)發(fā)的人就知道程序的規范性對他們來(lái)說(shuō)是有多么的重要。
 

 

　　關(guān)于編程規范及原則

　　編程規范也就是編寫(xiě)出簡(jiǎn)潔、可維護、可靠、可測試、高效、可移植的代碼，提高產(chǎn)品代碼的質(zhì)量。

　　本文針對嵌入式，主要結合C語(yǔ)言編程的規范給大家講述。

　　1.頭文件

　　對于C語(yǔ)言來(lái)說(shuō)，頭文件的設計體現了大部分的系統設計，不合理的頭文件布局是編譯時(shí)間過(guò)長(cháng)的原因。

　　有很多人將工程中所有的頭文件包含在一個(gè)include.h文件中，然后在每一個(gè).c源代碼文件中包含include.h頭文件，這樣做可以讓代碼看上去簡(jiǎn)潔，但實(shí)際忽視了編譯效率問(wèn)題，而且代碼的可移植性也不好。

　　原則：

　　A.頭文件中適合放置接口的聲明，不適合放置實(shí)現;

　　B.頭文件應當職責單一;

　　C.頭文件應向穩定的方向包含。

　　規則：

　　A.每一個(gè).c文件應有一個(gè)同名.h文件，用于聲明需要對外公開(kāi)的接口;

　　B.禁止頭文件循環(huán)依賴(lài);

　　C..c/.h文件禁止包含用不到的頭文件;

　　D.頭文件應當自包含;

　　E.總是編寫(xiě)內部#include保護符( #define 保護);

　　F.禁止在頭文件中定義變量;

　　G.只能通過(guò)包含頭文件的方式使用其他.c提供的接口，禁止在.c中通過(guò)extern的方式使用外部函數接口、變量;

　　H.禁止在extern "C"中包含頭文件。

　　建議：

　　A.一個(gè)模塊通常包含多個(gè).c文件，建議放在同一個(gè)目錄下，目錄名即為模塊名。為方便外部使用者，建議每一個(gè)模塊提供一個(gè).h，文件名為目錄名;

　　B.如果一個(gè)模塊包含多個(gè)子模塊，則建議每一個(gè)子模塊提供一個(gè)對外的.h，文件名為子模塊名(降低接口使用者的編寫(xiě)難度);

　　C.頭文件不要使用非習慣用法的擴展名，如.inc;

　　D.同一產(chǎn)品統一包含頭文件排列方式。

　　2.函數

　　函數設計的要點(diǎn)：編寫(xiě)整潔的函數，同時(shí)把代碼有效組織起來(lái)。

　　函數整潔的要求：代碼簡(jiǎn)單直接、不隱藏設計者的意圖、用干凈利落的抽象和直截了當的控制語(yǔ)句將函數有機組織起來(lái)。

　　原則：

　　A.一個(gè)函數僅完成一件功能;

　　B.重復代碼應該盡可能提煉成函數.

　　規則：

　　A.避免函數過(guò)長(cháng)，新增函數不超過(guò)100行(非空非注釋行);

　　B.避免函數的代碼塊嵌套過(guò)深，新增函數的代碼塊嵌套不超過(guò)4層;

　　C.可重入函數應避免使用共享變量;若需要使用，則應通過(guò)互斥手段(關(guān)中斷、信號量)對其加以保護;

　　D.對參數的合法性檢查，由調用者負責還是由接口函數負責，應在項目組/模塊內應統一規定;

　　E.對函數的錯誤返回碼要全面處理;

　　F.設計高扇入，合理扇出(小于7)的函數;

　　G.廢棄代碼(沒(méi)有被調用的函數和變量)要及時(shí)清除。

　　建議：

　　A.函數不變參數使用const;

　　B.函數應避免使用全局變量、靜態(tài)局部變量和I/O操作，不可避免的地方應集中使用;

　　C.檢查函數所有非參數輸入的有效性，如數據文件、公共變量等;

　　D.函數的參數個(gè)數不超過(guò)5個(gè);

　　E.除打印類(lèi)函數外，不要使用可變長(cháng)參函數;

　　F.在源文件范圍內聲明和定義的所有函數，除非外部可見(jiàn)，否則應該增加static關(guān)鍵字。

　　3.標識符命名與定義

　　程序命名是一個(gè)關(guān)鍵，如果命名不規范，自己寫(xiě)的代碼，時(shí)間長(cháng)了恐怕連自己都不知道是什么意思了。

　　3.1通用命名規則

　　常見(jiàn)命名風(fēng)格：

　　A.用下劃線(xiàn)„_?分割，如text_mutex;

　　B.大小寫(xiě)字母混用，如ReadRFCText。

　　規則：

　　A.標識符的命名要清晰、明了，有明確含義，同時(shí)使用完整的單詞或大家基本可以理解的縮寫(xiě)，避免使人產(chǎn)生誤解;

　　B.除了常見(jiàn)的通用縮寫(xiě)以外，不使用單詞縮寫(xiě)，不得使用漢語(yǔ)拼音;

　　C.產(chǎn)品/項目組內部應保持統一的命名風(fēng)格.

　　建議：

　　A.用正確的反義詞組命名具有互斥意義的變量或相反動(dòng)作的函數等;

　　B.盡量避免名字中出現數字編號，除非邏輯上的確需要編號;

　　C.標識符前不應添加模塊、項目、產(chǎn)品、部門(mén)的名稱(chēng)作為前綴;

　　D.平臺/驅動(dòng)等適配代碼的標識符命名風(fēng)格保持和平臺/驅動(dòng)一致;

　　E.重構/修改部分代碼時(shí)，應保持和原有代碼的命名風(fēng)格一致。

　　3.2 文件命名規則

　　因為不同系統對文件名大小寫(xiě)處理會(huì )不同，建議文件命名統一采用小寫(xiě)字符。

　　3.3 變量命名規則

　　首先，全局變量十分危險，通過(guò)前綴使得全局變量更加醒目， 促使開(kāi)發(fā)人員對這些變量的使用更加小心。

　　其次，從根本上說(shuō)，應當盡量不使用全局變量，增加g_和s_前綴，會(huì )使得全局變量的名字顯得很丑陋，從而促使開(kāi)發(fā)人員盡量少使用全局變量。

　　規則：

　　A.全局變量增加“g_”前綴，靜態(tài)變量增加“s_”前綴;

　　B.禁止使用單字節命名變量，但允許定義i、 j、 k作為局部循環(huán)變量;

　　C.使用名詞或者形容詞+名詞方式命名變量。

　　3.4 函數命名規則

　　A.函數命名應以函數要執行的動(dòng)作命名，一般采用動(dòng)詞或者動(dòng)詞+名詞的結構;

　　B.函數指針除了前綴，其他按照函數的命名規則命名。

　　3.5 宏的命名規則

　　A.對于數值或者字符串等等常量的定義，建議采用全大寫(xiě)字母，單詞之間加下劃線(xiàn)„_?的方式命名(枚舉同樣建議使用此方式定義);

　　B.除了頭文件或編譯開(kāi)關(guān)等特殊標識定義，宏定義不能使用下劃線(xiàn)„_?開(kāi)頭和結尾。

　　4.變量

　　原則：

　　A.一個(gè)變量只有一個(gè)功能，不能把一個(gè)變量用作多種用途;

　　B.結構功能單一;不要設計面面俱到的數據結構;

　　C.不用或者少用全局變量。

　　規則：

　　A.防止局部變量與全局變量同名;

　　B.通訊過(guò)程中使用的結構，必須注意字節序;

　　C.嚴禁使用未經(jīng)初始化的變量作為右值;

　　建議：

　　A.構造僅有一個(gè)模塊或函數可以修改、創(chuàng )建，而其余有關(guān)模塊或函數只訪(fǎng)問(wèn)的全局變量，防止多個(gè)不同模塊或函數都可以修改、創(chuàng )建同一全局變量的現象;

　　B.使用面向接口編程思想，通過(guò)API訪(fǎng)問(wèn)數據：如果本模塊的數據需要對外部模塊開(kāi)放，應提供接口函數來(lái)設置、獲取，同時(shí)注意全局數據的訪(fǎng)問(wèn)互斥;

　　C.在首次使用前初始化變量，初始化的地方離使用的地方越近越好;

　　D.明確全局變量的初始化順序，避免跨模塊的初始化依賴(lài);

　　E.盡量減少沒(méi)有必要的數據類(lèi)型默認轉換與強制轉換。

　　5.宏、常量

　　因為宏只是簡(jiǎn)單的代碼替換，不會(huì )像函數一樣先將參數計算后，再傳遞。

　　規則：

　　A.用宏定義表達式時(shí)，要使用完備的括號;

　　不規范：#define RECTANGLE_AREA(a, b) a * b

　　規范：#define RECTANGLE_AREA(a, b) ((a) * (b))

　　B.將宏所定義的多條表達式放在大括號中;

　　C.使用宏時(shí)，不允許參數發(fā)生變化;

　　#define SQUARE(a) ((a) * (a))

　　int a = 5;

　　int b;

　　不規范：

　　b = SQUARE(a++);

　　規范：

　　b = SQUARE(a);

　　a++;

　　建議：

　　A.除非必要，應盡可能使用函數代替宏;

　　B.常量建議使用const定義代替宏;

　　C.宏定義中盡量不使用return、 goto、 continue、 break等改變程序流程的語(yǔ)句。

　　6.注釋

　　原則：

　　A.優(yōu)秀的代碼可以自我解釋?zhuān)煌ㄟ^(guò)注釋即可輕易讀懂;

　　B.注釋的內容要清楚、明了，含義準確，防止注釋二義性;

　　C.在代碼的功能、意圖層次上進(jìn)行注釋?zhuān)醋⑨尳忉尨a難以直接表達的意圖，而不是重復描述代碼。

　　規則：

　　A.修改代碼時(shí)，維護代碼周邊的所有注釋?zhuān)员ＷC注釋與代碼的一致性。不再有用的注釋要刪;

　　B.文件頭部應進(jìn)行注釋?zhuān)⑨尡仨毩谐觯喊鏅嗾f(shuō)明、版本號、生成日期、作者姓名、工號、內容、功能說(shuō)明、與其它文件的關(guān)系、修改日志等，頭文件的注釋中還應有函數功能簡(jiǎn)要說(shuō)明;

　　C.函數聲明處注釋描述函數功能、性能及用法，包括輸入和輸出參數、函數返回值、可重入的要求等;定義處詳細描述函數功能和實(shí)現要點(diǎn)，如實(shí)現的簡(jiǎn)要步驟、實(shí)現的理由、 設計約束等;

　　D.全局變量要有較詳細的注釋?zhuān)▽ζ涔δ?、取值范圍以及存取時(shí)注意事項等的說(shuō)明;

　　E.注釋?xiě)旁谄浯a上方相鄰位置或右方，不可放在下面。 如放于上方則需與其上面的代碼用空行隔開(kāi)，且與下方代碼縮進(jìn)相同;

　　F.避免在注釋中使用縮寫(xiě)，除非是業(yè)界通用或子系統內標準化的縮寫(xiě);

　　G.同一產(chǎn)品或項目組統一注釋風(fēng)格。

　　建議：

　　A.避免在一行代碼或表達式的中間插入注釋;

　　B.文件頭、函數頭、全局常量變量、類(lèi)型定義的注釋格式采用工具可識別的格式。

　　7.排版與格式

　　規則：

　　A.程序塊采用縮進(jìn)風(fēng)格編寫(xiě)， 每級縮進(jìn)為4個(gè)空格;

　　B.相對獨立的程序塊之間、變量說(shuō)明之后必須加空行;

　　C.一條語(yǔ)句不能過(guò)長(cháng)，如不能拆分需要分行寫(xiě)。一行到底多少字符換行比較合適，產(chǎn)品可以自行確定;

　　D.多個(gè)短語(yǔ)句(包括賦值語(yǔ)句)不允許寫(xiě)在同一行內，即一行只寫(xiě)一條語(yǔ)句;

　　E.if、 for、 do、 while、 case、 switch、 default等語(yǔ)句獨占一行;

　　F.在兩個(gè)以上的關(guān)鍵字、變量、常量進(jìn)行對等操作時(shí)，它們之間的操作符之前、之后或者前后要加空格; 進(jìn)行非對等操作時(shí)，如果是關(guān)系密切的立即操作符(如->)，后不應加空格;

　　G.注釋符(包括„/*?„//?„*/?)與注釋內容之間要用一個(gè)空格進(jìn)行分隔。