一文讀懂｜C語言編碼規范

剛開始學STM32的時候，看到一些比較規范的代碼中的一些變量命名為ucValue 、g_ucPara等形式，為什么要加uc、g_uc等，這些前綴都有其約定俗成的意思，可以方便的知道變量的數據類型。如：uc代表的是unsigned char，所以一個變量命名為ucValue就可以清楚的表明其為unsigned char的變量 。同樣的，g代表global，即全局的，g_ucPara表明其為unsigned char類型的全局變量。

每個公司都有每個公司的編碼規范，今天我們來看網上的一些比較權威的編碼規范，比如安富萊的編碼規范：

文件與目錄

（1）文件的命名

文件的命名要準確清晰地表達其內容，同時文件名應該精練，防止文件名過長而造成使用不便。在文件名中可以適當地使用縮寫。以下提供兩種命名方式以供參考：

• 各程序模塊的文件命名開頭 2 個消協字母代表本模塊的功能：

如：主控程序為 mpMain.c，mpDisp.c 等。

• 不寫模塊功能標識：

如：主控程序為 Main.c，Disp.c 等。

（2）頭文件中段落安排順序

// 1、文件頭注釋
// 2、防止重復引用頭文件的設置
// 3、#include 部分
// 4、enum 常量聲明
// 5、類型聲明和定義，包括 struct、union、typedef 等
// 6、全局變量聲明
// 7、文件級變量聲明
// 8、全局或文件級函數聲明
// 9、函數實現。按函數聲明的順序排列
// 10、文件尾注釋

（3）在引用頭文件時，不要使用絕對路徑

如果使用絕對路徑，當需要移動目錄時，必須修改所有相關代碼，繁瑣且不安全；使用相對路徑，當需要移動目錄時，只需修改編譯器的某個選項即可。例如：

#include “/project/inc/hello.h” /* 不應使用絕對路徑 */
#include “../inc/hello.h”            /* 可以使用相對路徑 */

（4）在引用頭文件時 ，使用<>還是""        

#include <stdio.h>          /* 標準頭文件 */
#include <projdefs.h>     /* 工程制定目錄頭文件 */
#include “global.h”         /* 當前目錄頭文件 */
#include “inc/config.h” /* 路徑相對于當前目錄的頭文件 */

（5）防止頭文件被重復引用

#ifndef __DISP_H /* 文件名前名加兩個下劃線“__”，后面加 “_H”
#define __DISP_H
...
...
#endif

（6）頭文件中只存放“聲明”而不存放“定義”

（7）文件的長度

文件的長度沒有非常嚴格的要求，但應盡量避免文件過長。一般來說，文件長度應盡量保持在 1000 行之內 。

排版

（1）程序塊要采用縮進風格編寫，縮進的空格數為 4 個。

（2）相對獨立的程序塊之間、變量說明之后必須加空行 。

（3） 較長的語句或函數過程參數（>80 字符）要分成多行書寫，長表達式要在低優先級操作符處劃分新行，操作符放在新行之首，劃分出的新行要進行適當的縮進，使排版整齊，語句可讀。

（4） 不允許把多個短語句寫在一行中，即一行只寫一條語句

（5）程序塊的分界符（如大括號‘{’和‘}’ ）應各獨占一行并且位于同一列

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

示例：

• 逗號、分號只在后面加空格。

• 比較操作符，賦值操作符"="、 "+="，算術操作符"+"、"%"，邏輯操作符"&&"、"&"，位域操作符"<<"、"^"等雙目操作符的前后加空格。

• "!"、"~"、"++"、"--"、"&"（地址運算符）等單目操作符前后不加空格。

• "->"、"."前后不加空格。

• if、for、while、switch 等與后面的括號間應加空格，使 if 等關鍵字更為突出、明顯，函數名與其后的括號之間不加空格，以與保留字區別開。

注釋

（1） 一般的，源程序有效注釋量必須在 20％以上。

說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加，注釋不宜太多也不能太少，注釋語言必須準確、易懂、簡潔 。

（2） 在文件的開始部分，應該給出關于文件版權、內容簡介、修改歷史等項目的說明。

在創建代碼和每次更新代碼時，都必須在文件的歷史記錄中標注版本號、日期、作者、更改說明等項目。下面是一個范例，當然，并不局限于此格式，但上述信息建議要包含在內。

（3）對于函數，在函數實現之前，應該給出和函數的實現相關的足夠而精練的注釋信息。

示例：

下面這段函數的注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內。

（4） 邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。不再有用的注釋要刪除。

（5） 注釋的內容要清楚、明了，含義準確，防止注釋二義性。

說明：錯誤的注釋不但無益反而有害。注釋主要闡述代碼做了什么（What），或者如果有必要的話，闡述為什么要這么做（Why），注釋并不是用來闡述它究竟是如何實現算法（How）的。

（6） 避免在注釋中使用縮寫，特別是非常用縮寫。

說明：在使用縮寫時或之前，應對縮寫進行必要的說明。

（7） 注釋應與其描述的代碼靠近，對代碼的注釋應放在其上方或右方（對單條語句的注釋）相鄰位置，不可放在下面，如放于上方則需與其上面的代碼用空行隔開。

示例：如下例子不符合規范。

例 1：不規范的寫法

例 2：不規范的寫法

例 3：規范的寫法

例 4：不規范的寫法，顯得代碼過于緊湊

例 5：規范的寫法

（8） 注釋與所描述內容進行同樣的縮排。

說明：可使程序排版整齊，并方便注釋的閱讀與理解。

例 1：如下例子，排版不整齊，閱讀稍感不方便。

例 2：正確的布局。

（9） 對變量的定義和分支語句（條件分支、循環語句等）必須編寫注釋。

說明：這些語句往往是程序實現某一特定功能的關鍵，對于維護人員來說，良好的注釋幫助更好的理解程序，有時甚至優于看設計文檔。

（10） 對于 switch 語句下的 case 語句，如果因為特殊情況需要處理完一個 case 后進入下一個 case 處理，必須在該 case 語句處理完、下一個 case 語句前加上明確的注釋。

說明：這樣比較清楚程序編寫者的意圖，有效防止無故遺漏 break 語句。

示例（注意斜體加粗部分）：

（11） 注釋格式盡量統一，建議使用“/* …… */”，因為 C++注釋“//”并不被所有 C 編譯器支持。

（12） 注釋應考慮程序易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能非常流利準確的用英文表達。

說明：注釋語言不統一，影響程序易讀性和外觀排版，出于對維護人員的考慮，建議使用中文。

（13） 標識符的命名要清晰、明了，有明確含義，同時使用完整的單詞或大家基本可以理解的縮寫，避免使人產生誤解。

說明：較短的單詞可通過去掉“元音”形成縮寫；較長的單詞可取單詞的頭幾個字母形成縮寫；一些單詞有大家公認的縮寫。

示例：如下單詞的縮寫能夠被大家基本認可。

temp 可縮寫為 tmp;
flag 可縮寫為 flg;
statistic 可縮寫為 stat;
increment 可縮寫為 inc;
message 可縮寫為 msg;

（14） 命名中若使用特殊約定或縮寫，則要有注釋說明。

說明：應該在源文件的開始之處，對文件中所使用的縮寫或約定，特別是特殊的縮寫，進行必要的注釋說明。

（15） 自己特有的命名風格，要自始至終保持一致，不可來回變化。

說明：個人的命名風格，在符合所在項目組或產品組的命名規則的前提下，才可使用。（即命名規則中沒有規定到的地方才可有個人命名風格）

（16） 對于變量命名，禁止取單個字符（如 i、j、k…）

建議除了要有具體含義外，還能表明其變量類型、數據類型等，但 i、j、k 作局部循環變量是允許的。

變量，尤其是局部變量，如果用單個字符表示，很容易敲錯（如i寫成j），而編譯時又檢查不出來，有可能為了這個小小的錯誤而花費大量的查錯時間 。

（17） 命名規范必須與所使用的系統風格保持一致，并在同一項目中統一

比如采用 UNIX 的全小寫加下劃線的風格或大小寫混排的方式，不要使用大小寫與下劃線混排的方式，用作特殊標識如標識成員變量或全局變量的 m_和 g_，其后加上大小寫混排的方式是允許的。
示例：Add_User不允許，add_user、AddUser、m_AddUser允許。

（18） 除非必要，不要用數字或較奇怪的字符來定義標識符。

示例：如下命名，使人產生疑惑。

應改為有意義的單詞命名：

可讀性

（1） 注意運算符的優先級，并用括號明確表達式的操作順序，避免使用默認優先級。

（2） 避免使用不易理解的數字，用有意義的標識來替代。

示例：如下的程序可讀性差

應改為如下形式 ：

（3） 不要使用難懂的技巧性很高的語句，除非很有必要時。

說明：高技巧語句不等于高效率的程序，實際上程序的效率關鍵在于算法。

示例：如下表達式，考慮不周就可能出問題，也較難理解。

應分別改為如下：

變量、結構、常量、宏

（1） 為了方便書寫及記憶，變量類型采用如下重定義：

（2） 常見類型的前綴

• 對于一些常見類型的變量，應在其名字前標注表示其類型的前綴。前綴用小寫字母表示。前綴的使用請參照下列表格中說明。

（3） 變量作用域的前綴

為了清晰的標識變量的作用域，減少發生命名沖突，應該在變量類型前綴之前再加上表示變量作用域的前綴，并在變量類型前綴和變量作用域前綴之間用下劃線 - 隔開。

具體的規則如下：

• 對于全局變量（global variable），在其名稱前加g和變量類型符號前綴。

  uint32_t g_ulParaWord;
  uint8_t g_ucByte;

• 對于靜態變量（static variable），在其名稱前加s和變量類型符號前綴。

  static uint32_t s_ulParaWord;
  static uint8_t s_ucByte;

• 函數內部等局部變量前不加作用域前綴。

• 對于常量，當可能發生作用域和名字沖突問題時，以上幾條規則對于常量同樣適用。注意，雖然常量名的核心部分全部大寫，但此時常量的前綴仍然用小寫字母，以保持前綴的一致性。

（4） 結構體命名規則

表示類型的名字，所有名字以小寫字母tag開頭，之后每個英文單詞的第一個字母大寫（包括第一個單詞的第一個字母），其他字母小寫，結尾_T 標識。單詞之間不使用下劃線分隔,結構體變量以 t 開頭。如：

/* 結構體命名類型名 */
typedef struct tagBillQuery_T
{
...
}BillQuery_T;
/* 結構體變量定義 */
BillQuery_T tBillQuery;

（5）對于枚舉定義全部采用大寫，結尾_E 標識。

（6）常量、宏、模版的名字應該全部大寫。如果這些名字由多個單詞組成，則單詞之間用下劃線分隔。

#define LOG_BUF_SIZE 8000

函數

（1） 函數的命名規則。

每一個函數名前綴需包含模塊名，模塊名為小寫，與函數名區別開。

如：uartReceive(串口接收)

備注：對于非常簡單的程序，可以不加模塊名。

（2）函數的形參。

函數的的形參都以下劃線_開頭，已示與普通變量進行區分，對于沒有形參為空的函數(void)括號緊跟函數后面。

uint32_t uartConvUartBaud(uint32_t _ulBaud)
{
}

（3） 一個函數僅完成一件功能。

（4） 函數名應準確描述函數的功能，使用動賓詞組為執行某操作的函數命名。

說明：避免用含義不清的動詞如process、handle等為函數命名，因為這些動詞并沒有說明要具體做什么。

示例：參照如下方式命名函數。

（5）避免設計五個以上參數函數，不使用的參數從接口中去掉。

說明：目的減少函數間接口的復雜度，復雜的參數可以使用結構傳遞。

（6）在調用函數填寫參數時，應盡量減少沒有必要的默認數據類型轉換或強制數據類型轉換。

說明：因為數據類型轉換或多或少存在危險。

（7） 防止把沒有關聯的語句放到一個函數中。

示例：如下函數就是一種隨機內聚。

矩形的長、寬與點的坐標基本沒有任何關系，故以上函數是隨機內聚。應如下分為兩個函數：