關(guān)于軟件開(kāi)發(fā)編程規(guī)范及原則

寫(xiě)在前面 Ⅰ

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

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

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

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

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

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

1.頭文件

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

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

原則：

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

B.頭文件應(yīng)當(dāng)職責(zé)單一;

C.頭文件應(yīng)向穩(wěn)定的方向包含。

規(guī)則：

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

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

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

D.頭文件應(yīng)當(dāng)自包含;

E.總是編寫(xiě)內(nèi)部#include保護(hù)符（ #define 保護(hù)）;

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

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

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

建議：

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

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

C.頭文件不要使用非習(xí)慣用法的擴(kuò)展名，如.inc;

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

2.函數(shù)

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

函數(shù)整潔的要求：代碼簡(jiǎn)單直接、不隱藏設(shè)計(jì)者的意圖、用干凈利落的抽象和直截了當(dāng)?shù)目刂普Z(yǔ)句將函數(shù)有機(jī)組織起來(lái)。

原則：

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

B.重復(fù)代碼應(yīng)該盡可能提煉成函數(shù).

規(guī)則：

A.避免函數(shù)過(guò)長(zhǎng)，新增函數(shù)不超過(guò)100行（非空非注釋行）;

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

C.可重入函數(shù)應(yīng)避免使用共享變量；若需要使用，則應(yīng)通過(guò)互斥手段（關(guān)中斷、信號(hào)量）對(duì)其加以保護(hù);

D.對(duì)參數(shù)的合法性檢查，由調(diào)用者負(fù)責(zé)還是由接口函數(shù)負(fù)責(zé)，應(yīng)在項(xiàng)目組/模塊內(nèi)應(yīng)統(tǒng)一規(guī)定;

E.對(duì)函數(shù)的錯(cuò)誤返回碼要全面處理;

F.設(shè)計(jì)高扇入，合理扇出（小于7）的函數(shù);

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

建議：

A.函數(shù)不變參數(shù)使用const;

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

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

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

E.除打印類函數(shù)外，不要使用可變長(zhǎng)參函數(shù);

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

3.標(biāo)識(shí)符命名與定義

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

3.1通用命名規(guī)則

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

A.用下劃線?_?分割，如text_mutex;

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

規(guī)則：

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

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

C.產(chǎn)品/項(xiàng)目組內(nèi)部應(yīng)保持統(tǒng)一的命名風(fēng)格.

建議：

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

B.盡量避免名字中出現(xiàn)數(shù)字編號(hào)，除非邏輯上的確需要編號(hào);

C.標(biāo)識(shí)符前不應(yīng)添加模塊、項(xiàng)目、產(chǎn)品、部門(mén)的名稱作為前綴;

D.平臺(tái)/驅(qū)動(dòng)等適配代碼的標(biāo)識(shí)符命名風(fēng)格保持和平臺(tái)/驅(qū)動(dòng)一致;

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

3.2 文件命名規(guī)則

因?yàn)椴煌到y(tǒng)對(duì)文件名大小寫(xiě)處理會(huì)不同，建議文件命名統(tǒng)一采用小寫(xiě)字符。

3.3 變量命名規(guī)則

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

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

規(guī)則：

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

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

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

3.4 函數(shù)命名規(guī)則

A.函數(shù)命名應(yīng)以函數(shù)要執(zhí)行的動(dòng)作命名，一般采用動(dòng)詞或者動(dòng)詞＋名詞的結(jié)構(gòu);

B.函數(shù)指針除了前綴，其他按照函數(shù)的命名規(guī)則命名。

3.5 宏的命名規(guī)則

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

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

4.變量

原則：

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

B.結(jié)構(gòu)功能單一；不要設(shè)計(jì)面面俱到的數(shù)據(jù)結(jié)構(gòu);

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

規(guī)則：

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

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

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

建議：

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

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

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

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

E.盡量減少?zèng)]有必要的數(shù)據(jù)類型默認(rèn)轉(zhuǎn)換與強(qiáng)制轉(zhuǎn)換。

5.宏、常量

因?yàn)楹曛皇呛?jiǎn)單的代碼替換，不會(huì)像函數(shù)一樣先將參數(shù)計(jì)算后，再傳遞。

規(guī)則：

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

不規(guī)范：#defineRECTANGLE_AREA(a, b) a * b

規(guī)范：#defineRECTANGLE_AREA(a, b) ((a) * (b))

B.將宏所定義的多條表達(dá)式放在大括號(hào)中;

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

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

int a = 5;

int b;

不規(guī)范：

b = SQUARE(a++);

規(guī)范：

b = SQUARE(a);

a++;

建議：

A.除非必要，應(yīng)盡可能使用函數(shù)代替宏;

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

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

6.注釋

原則：

A.優(yōu)秀的代碼可以自我解釋，不通過(guò)注釋即可輕易讀懂;

B.注釋的內(nèi)容要清楚、明了，含義準(zhǔn)確，防止注釋二義性;

C.在代碼的功能、意圖層次上進(jìn)行注釋，即注釋解釋代碼難以直接表達(dá)的意圖，而不是重復(fù)描述代碼。

規(guī)則：

A.修改代碼時(shí)，維護(hù)代碼周邊的所有注釋，以保證注釋與代碼的一致性。不再有用的注釋要?jiǎng)h;

B.文件頭部應(yīng)進(jìn)行注釋，注釋必須列出：版權(quán)說(shuō)明、版本號(hào)、生成日期、作者姓名、工號(hào)、內(nèi)容、功能說(shuō)明、與其它文件的關(guān)系、修改日志等，頭文件的注釋中還應(yīng)有函數(shù)功能簡(jiǎn)要說(shuō)明;

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

D.全局變量要有較詳細(xì)的注釋，包括對(duì)其功能、取值范圍以及存取時(shí)注意事項(xiàng)等的說(shuō)明;

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

F.避免在注釋中使用縮寫(xiě)，除非是業(yè)界通用或子系統(tǒng)內(nèi)標(biāo)準(zhǔn)化的縮寫(xiě);

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

建議：

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

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

7.排版與格式

規(guī)則：

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

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

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

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

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

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

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

說(shuō)明 Ⅲ

關(guān)于編程規(guī)范、原則等相關(guān)的文章在國(guó)外很多優(yōu)秀的工程師都總結(jié)的有：

http://www.artima.com/weblogs/viewpost.jsp?thread=331531

良好的編程習(xí)慣是需要日積月累的，如果你處于學(xué)習(xí)階段，請(qǐng)你時(shí)刻要注意這些細(xì)節(jié)問(wèn)題。