【code】通用C程式碼規範
文章目錄
- 1.目錄名稱
- 2.檔名稱
- 3.標頭檔案定義
- 4.檔案頭註釋
- 5.結構體定義
- 6.巨集定義
- 7.函式名稱、宣告
- 8.註釋編寫
- 9.縮排及分行
- 10.大括號與空格
- 11函式
- 12.物件
- 13. 用 astyle 自動格式化程式碼
1.目錄名稱
目錄名稱如果無特殊的需求,請使用全小寫的形式;
目錄名稱應能夠反應部分的意思,例如各晶片移植由其晶片名稱構成或晶片類別構成;
2.檔名稱
檔名稱如果無特殊的需求(如果是引用其他地方,可以保留相應的名稱),請使用全小寫的形式。
另外為了避免檔名重名的問題,一些地方請儘量不要使用通用化、使用頻率高的名稱。
3.標頭檔案定義
C語言標頭檔案為了避免多次重複包含,需要定義一個符號。這個符號的定義形式請採用如下
的風格:
#ifndef __FILE_H__
#define __FILE_H__
/* header file content */
#endif
即定義的符號兩側採用 “__” 以避免重名,另外也可以根據檔名中是否包含多個詞語而
採用 “_” 連線起來。
4.檔案頭註釋
在每個原始檔檔案頭上,應該包括相應的版權資訊,Change Log 記錄:
/*
* Copyright (c) 2006-2020, xxx Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
* Change Logs:
* Date Author Notes
* xxxx-xx-xx xxx the first version
* xxxx-xx-xx xxx add semaphore APIs
*/
例如採用如上的形式。
5.結構體定義
結構體名稱請使用小寫英文名的形式,單詞與單詞之間採用 “_” 連線,例如:
struct xx_list_node
{
struct xx_list_node *next;
struct xx_list_node *prev;
};
其中,"{","}" 獨立佔用一行,後面的成員定義使用縮排的方式定義。
結構體等的型別定義請以結構體名稱加上 “_t” 的形式作為名稱,例如:
typedef struct xx_list_node rt_list_t;
因為核心中物件引用方便的緣故,採用了物件核心指標作為型別定義的形式,例如:
typedef struct xx_timer* xx_timer_t;
6.巨集定義
使用大寫英文名稱作為巨集定義,單詞之間使用 “_” 連線,例如:
#define XX_TRUE 1
7.函式名稱、宣告
函式名稱請使用小寫英文的形式,單詞之間使用 “_” 連線。提供給上層應用使用的 API介面,必須在相應的標頭檔案中宣告;如果函式入口引數是空,必須使用 void 作為入口引數,例如:
xx_thread_t xx_thread_self(void);
8.註釋編寫
-
使用英文做為註釋
-
對語句的註釋只能寫在它的上方或右方
9.縮排及分行
縮排請採用 4 個空格的方式。如果沒有什麼特殊意義,請在 “{” 後進行分行,並在下一行都採用縮排的方式,例如:
if (condition)
{
/* others */
}
唯一的例外是 switch 語句,switch-case 語句採用 case 語句與 switch 對齊的方式,
例如:
switch (value)
{
case value1:
break;
}
case 語句與前面的 switch 語句對齊,後續的語句則採用縮排的方式。
分行上,如果沒有什麼特殊考慮,請不要在程式碼中連續使用兩個以上的空行。
10.大括號與空格
從程式碼閱讀角度,建議每個大括號單獨佔用一行,而不是跟在語句的後面,例如:
if (condition)
{
/* others */
}
匹配的大括號單獨佔用一行,程式碼閱讀起來就會有相應的層次而不會容易出現混淆的情況。
空格建議在非函式方式的括號呼叫前留一個空格以和前面的進行區分,例如:
if (x <= y)
{
/* others */
}
for (index = 0; index < MAX_NUMBER; index ++)
{
/* others */
}
建議在括號前留出一個空格(涉及的包括 if、for、while、switch 語句),而運算表示式
中,運算子與字串間留一個空格。另外,不要在括號的表示式兩側留空格,例如:
if ( x <= y )
{
/* other */
}
這樣括號內兩側的空格是不允許的。
11函式
在核心程式設計中,函式應該儘量精簡,僅完成相對獨立的簡單功能。函式的實現不應該太長,函式實現太長,應該反思能夠如何修改(或拆分)使得函式更為精簡、易懂。
12.物件
採用 C 語言物件化技術,命名錶現形式是:物件名結構體表示類定義、
物件名 + 動詞短語形式表示類方法,例如:
struct xx_timer
{
struct xx_object parent;
/* other fields */
};
typedef struct xx_timer* xx_timer_t;
結構體定義 xx_timer 代表了 timer 物件的類定義;
xx_timer_t xx_timer_create(const char* name,
void (*timeout)(void* parameter), void* parameter,
xx_tick_t time, xx_uint8_t flag);
xx_err_t xx_timer_delete(xx_timer_t timer);
xx_err_t xx_timer_start(xx_timer_t timer);
xx_err_t xx_timer_stop(xx_timer_t timer);
xx_timer + 動詞短語的形式表示能夠應用於 timer 物件的方法。
在建立一個新的物件時,應該思考好,物件的記憶體操作處理:是否允許一個靜態物件存在,或僅僅支援從堆中動態分配的物件。
13. 用 astyle 自動格式化程式碼
引數:--style=allman
--indent=spaces=4
--indent-preproc-block
--pad-oper
--pad-header
--unpad-paren
--suffix=none
--align-pointer=name
--lineend=linux
--convert-tabs
--verbose