推薦

分享一個大神的人工智慧教程。零基礎！通俗易懂！風趣幽默！還帶黃段子！希望你也加入到人工智慧的隊伍中來！http://www.captainbed.net/strongerhuang

 

我的網站：https://www.strongerhuang.com

我的知乎：https://www.zhihu.com/people/strongerHuang.com

 

Ⅰ、寫在前面

不知道大家有沒有這樣的感受：看到不規範（雜亂差）的程式碼，瞬間就沒有看下去的慾望了。

 

相信大家看到標題都應該能明白程式設計的規範及原則對於每一個軟體開發的工程師來說是多麼重要。

 

初學者編寫測試程式、小的模組程式也許不能感受它的重要性；但有經驗及大型專案開發的人就知道程式的規範性對他們來說是有多麼的重要。

 

Ⅱ、關於程式設計規範及原則

程式設計規範也就是編寫出簡潔、可維護、可靠、可測試、高效、可移植的程式碼，提高產品程式碼的質量。

本文針對嵌入式，主要結合C語言程式設計的規範給大家講述。

 

1.標頭檔案

對於C語言來說，標頭檔案的設計體現了大部分的系統設計，不合理的標頭檔案佈局是編譯時間過長的原因。

 

有很多人將工程中所有的標頭檔案包含在一個include.h檔案中，然後在每一個.c原始碼檔案中包含include.h標頭檔案，這樣做可以讓程式碼看上去簡潔，但實際忽視了編譯效率問題，而且程式碼的可移植性也不好。

 

原則：

A.標頭檔案中適合放置介面的宣告，不適合放置實現；

B.標頭檔案應當職責單一;

C.標頭檔案應向穩定的方向包含。

 

規則：

A.每一個.c檔案應有一個同名.h檔案，用於宣告需要對外公開的介面;

B.禁止標頭檔案迴圈依賴;

C..c/.h檔案禁止包含用不到的標頭檔案;

D.標頭檔案應當自包含;

E.總是編寫內部#include保護符（ #define 保護）;

F.禁止在標頭檔案中定義變數;

G.只能通過包含標頭檔案的方式使用其他.c提供的介面，禁止在.c中通過extern的方式使用外部函式介面、變數;

H.禁止在extern "C"中包含標頭檔案。

 

建議：

A.一個模組通常包含多個.c檔案，建議放在同一個目錄下，目錄名即為模組名。為方便外部使用者，建議每一個模組提供一個.h，檔名為目錄名;

B.如果一個模組包含多個子模組，則建議每一個子模組提供一個對外的.h，檔名為子模組名（降低介面使用者的編寫難度）;

C.標頭檔案不要使用非習慣用法的副檔名，如.inc;

D.同一產品統一包含標頭檔案排列方式。

 

2.函式

函式設計的要點：編寫整潔的函式，同時把程式碼有效組織起來。

函式整潔的要求：程式碼簡單直接、不隱藏設計者的意圖、用乾淨利落的抽象和直截了當的控制語句將函式有機組織起來。

 

原則：

A.一個函式僅完成一件功能;

B.重複程式碼應該儘可能提煉成函式.

 

規則：

A.避免函式過長，新增函式不超過100行（非空非註釋行）;

B.避免函式的程式碼塊巢狀過深，新增函式的程式碼塊巢狀不超過4層;

C.可重入函式應避免使用共享變數；若需要使用，則應通過互斥手段（關中斷、訊號量）對其加以保護;

D.對引數的合法性檢查，由呼叫者負責還是由介面函式負責，應在專案組/模組內應統一規定;

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

F.設計高扇入，合理扇出（小於7）的函式;

G.廢棄程式碼（沒有被呼叫的函式和變數)要及時清除。

 

建議：

A.函式不變引數使用const;

B.函式應避免使用全域性變數、靜態區域性變數和I/O操作，不可避免的地方應集中使用;

C.檢查函式所有非引數輸入的有效性，如資料檔案、公共變數等;

D.函式的引數個數不超過5個;

E.除列印類函式外，不要使用可變長參函式;

F.在原始檔範圍內宣告和定義的所有函式，除非外部可見，否則應該增加static關鍵字。

 

3.識別符號命名與定義

程式命名是一個關鍵，如果命名不規範，自己寫的程式碼，時間長了恐怕連自己都不知道是什麼意思了。

 

3.1通用命名規則

常見命名風格：

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

B.大小寫字母混用，如ReadRFCText。

 

規則：

A.識別符號的命名要清晰、明瞭，有明確含義，同時使用完整的單詞或大家基本可以理解的縮寫，避免使人產生誤解；

B.除了常見的通用縮寫以外，不使用單詞縮寫，不得使用漢語拼音;

C.產品/專案組內部應保持統一的命名風格.

 

建議：

A.用正確的反義片語命名具有互斥意義的變數或相反動作的函式等;

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

C.識別符號前不應新增模組、專案、產品、部門的名稱作為字首;

D.平臺/驅動等適配程式碼的識別符號命名風格保持和平臺/驅動一致;

E.重構/修改部分程式碼時，應保持和原有程式碼的命名風格一致。

 

3.2 檔案命名規則

因為不同系統對檔名大小寫處理會不同，建議檔案命名統一採用小寫字元。

 

3.3 變數命名規則

首先，全域性變數十分危險，通過字首使得全域性變數更加醒目， 促使開發人員對這些變數的使用更加小心。

其次，從根本上說，應當儘量不使用全域性變數，增加g_和s_字首，會使得全域性變數的名字顯得很醜陋，從而促使開發人員儘量少使用全域性變數。

 

規則：

A.全域性變數增加“g_”字首，靜態變數增加“s_”字首;

B.禁止使用單位元組命名變數，但允許定義i、 j、 k作為區域性迴圈變數;

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

 

3.4 函式命名規則

A.函式命名應以函式要執行的動作命名，一般採用動詞或者動詞＋名詞的結構;

B.函式指標除了字首，其他按照函式的命名規則命名。

 

3.5 巨集的命名規則

A.對於數值或者字串等等常量的定義，建議採用全大寫字母，單詞之間加下劃線„_‟的方式命名（列舉同樣建議使用此方式定義）;

B.除了標頭檔案或編譯開關等特殊標識定義，巨集定義不能使用下劃線„_‟開頭和結尾。

 

4.變數

原則：

A.一個變數只有一個功能，不能把一個變數用作多種用途;

B.結構功能單一；不要設計面面俱到的資料結構;

C.不用或者少用全域性變數。

 

規則：

A.防止區域性變數與全域性變數同名;

B.通訊過程中使用的結構，必須注意位元組序;

C.嚴禁使用未經初始化的變數作為右值;

 

建議：

A.構造僅有一個模組或函式可以修改、建立，而其餘有關模組或函式只訪問的全域性變數，防止多個不同模組或函式都可以修改、建立同一全域性變數的現象;

B.使用面向介面程式設計思想，通過API訪問資料：如果本模組的資料需要對外部模組開放，應提供介面函式來設定、獲取，同時注意全域性資料的訪問互斥;

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

D.明確全域性變數的初始化順序，避免跨模組的初始化依賴;

E.儘量減少沒有必要的資料型別預設轉換與強制轉換。

 

5.巨集、常量

因為巨集只是簡單的程式碼替換，不會像函式一樣先將引數計算後，再傳遞。

 

規則：

A.用巨集定義表示式時，要使用完備的括號;

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

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

 

B.將巨集所定義的多條表示式放在大括號中;

C.使用巨集時，不允許引數發生變化;

#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等改變程式流程的語句。

 

6.註釋

原則：

A.優秀的程式碼可以自我解釋，不通過註釋即可輕易讀懂;

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

C.在程式碼的功能、意圖層次上進行註釋，即註釋解釋程式碼難以直接表達的意圖，而不是重複描述程式碼。

 

規則：

A.修改程式碼時，維護程式碼周邊的所有註釋，以保證註釋與程式碼的一致性。不再有用的註釋要刪;

B.檔案頭部應進行註釋，註釋必須列出：版權說明、版本號、生成日期、作者姓名、工號、內容、功能說明、與其它檔案的關係、修改日誌等，標頭檔案的註釋中還應有函式功能簡要說明;

C.函式宣告處註釋描述函式功能、效能及用法，包括輸入和輸出引數、函式返回值、可重入的要求等；定義處詳細描述函式功能和實現要點，如實現的簡要步驟、實現的理由、 設計約束等;

D.全域性變數要有較詳細的註釋，包括對其功能、取值範圍以及存取時注意事項等的說明;

E.註釋應放在其程式碼上方相鄰位置或右方，不可放在下面。 如放於上方則需與其上面的程式碼用空行隔開，且與下方程式碼縮排相同;

F.避免在註釋中使用縮寫，除非是業界通用或子系統內標準化的縮寫;

G.同一產品或專案組統一註釋風格。

 

建議：

A.避免在一行程式碼或表示式的中間插入註釋;

B.檔案頭、函式頭、全域性常量變數、型別定義的註釋格式採用工具可識別的格式。

 

7.排版與格式

規則：

A.程式塊採用縮排風格編寫， 每級縮排為4個空格;

B.相對獨立的程式塊之間、變數說明之後必須加空行;

C.一條語句不能過長，如不能拆分需要分行寫。一行到底多少字元換行比較合適，產品可以自行確定;

D.多個短語句（包括賦值語句）不允許寫在同一行內，即一行只寫一條語句;

E.if、 for、 do、 while、 case、 switch、 default等語句獨佔一行;

F.在兩個以上的關鍵字、變數、常量進行對等操作時，它們之間的操作符之前、之後或者前後要加空格； 進行非對等操作時，如果是關係密切的立即操作符（如－>），後不應加空格;

G.註釋符（包括„/*‟„//‟„*/‟）與註釋內容之間要用一個空格進行分隔。

 

Ⅲ、說明

關於程式設計規範、原則等相關的文章在國外很多優秀的工程師都總結的有：

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

 

良好的程式設計習慣是需要日積月累的，如果你處於學習階段，請你時刻要注意這些細節問題。

 

Ⅳ、最後

我的網站：https://www.strongerhuang.com

我的微信公眾號（ID：strongerHuang）還在分享STM8、STM32、Keil、IAR、FreeRTOS、UCOS、RT-Thread、CANOpen、Modbus…等更多精彩內容，如果想檢視更多內容，可以關注我的微信公眾號。