文章目录
1. 排版格式
1.1 Tab
设置每按一次Tab键,代码缩进4个空格。
1.2 swich - case
swich - case
必须要完整,必须包含最后的default
语句。swich
和case
标签应该对齐处于同一列。
switch (suffix)
{
case 'G':
case 'g':
mem <<= 30;
break;
case 'M':
case 'm':
mem <<= 20;
break;
case 'K':
case 'k':
mem <<= 10;
/* fall through */
default:
break;
}
- 对于
switch
语句下的case
语句,如果因为特殊情况需要处理完一个case
后进入下一个case
处理,必须在该case
语句处理完、下一个case
语句前加上明确的注释。
switch (suffix)
{
case 'G':
// 跳转到 'g'
case 'g':
mem <<= 30;
break;
case 'M':
// 跳转到 'm'
case 'm':
mem <<= 20;
break;
case 'K':
// 跳转到 'k'
case 'k':
mem <<= 10;
break;
default:
break;
}
1.3 一行只写一条语句
//不规范的写法:
a = x+y; b = x-y;
//规范的写法
a=x+y;
b=x-y;
1.4 括号的起止应独立占用一行
if (x is true)
{
we do y
}
int function(int x)
{
body of function
}
1.5 空格
- 在以下关键字后添加一个空格:
if、swich、case、for、do、while
. - 不要在
sizeof、typedof、alignof
或者__attribute__
这些关键字/运算符后面添加空格。 - 二元或者三元操作符两侧都要加一个空格。
= + - < > * / % | & ^ <= >= == != ? :
- 一元操作符后不要加空格。
& * + - ~ ! sizeof typeof alignof __attribute__ defined
- 后缀自加或者自减的一元操作符前后都不加空格。
++ --
.
和->
这两个结构体成员操作符前后不加空格。- 逗号、分号只在后面添加空格。
int a, b, c;
- 注释符
/
和*/
与注释内容之间要添加一个空格。
1.6 空行
- 相对独立的程序块之间、变量说明之后必须加空行。
void DemoFunc(void)
{
uint8_t i;//<---- 局部变量和语句间空一行
/* 功能块 1 */
for (i = 0; i < 10; i++)
{
...
}//<---- 不同的功能块间空一行
/* 功能块 2 */
for (i = 0; i < 20; i++)
{
...
}
}
1.7 括号
注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。
注:防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。
word = (high << 8) | low;
if ((a | b) && (a & c))
if ((a | b) < (c & d))
2. 注释
2.1 多行注释
注释头、尾使用80个*
号。
/********************************************************************************
This is the preferred style for multi-line
comments in the Linux kernel source code.
Please use it consistently.
Description: A column of asterisks on the left side,
with beginning and ending almost-blank lines.
********************************************************************************/
2.2 函数说明
/********************************************************************************
** 函数名称 : main
** 功能描述 : 工程入口函数
** 输入变量 : 无
** 返 回 值 :
0:程序执行正常
1:程序执行异常
** 最后修改人 : xxx
** 最后更新日期: 20210123
** 说 明 : 无
********************************************************************************/
2.3 代码块说明
位于函数内部的功能代码块,可用以下注释说明与高亮
/* xxx CODE BLOCK START */
...
/* xxx CODE BLOCK END */
2.4 代码修改备注
修改代码后,在修改的地方备注修改人、修改时间、修改内容。增加代码语句使用Add
,修改代码使用Mod
.
int a = 1; // Zhangshan Add - 增加变量定义 - 20210713
// Zhangshan Mod - 修改判断条件 - 20210713
if(...)
{
...
}
3. 变量、函数等规范
- 一个函数只能完成一个功能。
- 一个变量只能有一个功能。
- 宏定义、枚举标签使用全大写。如:
#define CONSTANT 0x12345
3.1 代码管理
3.1.1 README.txt文档
每个代码工程都应该包含一个README.txt
的文档以说明代码的功能和用法。
/*************************************************
* Project name:
* Author:
* Description: 用于详细说明此程序文件完成的主要功能,与其他模块或函数的接口,输出值、取值范围、含义及参数间的控制、顺序、独立或依赖等关系
* Others: 其它内容的说明
*************************************************/
3.1.2 UpdateLog.txt文档
每个代码工程都应该包含一个UpdateLog.txt
的文档以记录每次修改代码的记录,参考模板如下:
/************************************************************************************/
更新时间:
更新人:
更新后版本号:
更新内容:
1.
2.
3.
/************************************************************************************/
3.2 使用assert()
判断输入变量
如果约定由调用方检查参数输入,则应使用assert()之类的宏,来验证所有参数输入的有效性。
关于
assert()
的用法,详见C理论之二——运算符、三大结构、文件操作
3.3 复杂参数使用结构体进行参数传递
为了减少函数间接口的复杂度,复杂的参数或输入参数过多时可以使用结构传递。
4. 命名法
4.2 变量命名法
- 变量、函数命名使用驼峰命名法,命名尽量不使用英文缩写、建议使用全拼英文,不准使用拼音缩写和拼音拼写。如:
goHome
、motorEStop
. - 变量命名前缀增加分类标识,格式为:
分类组名_变量名
,如Motor_goHome
- 单个字符命名的变量
i
、j
、k
仅建议在局部变量中使用。
4.3 使用枚举、宏定义代替数字
避免使用不易理解的数字,用有意义的标识来替代。涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的枚举或宏来代替。
enum trunk_state_e
{
TRUNK_IDLE = 0,
TRUNK_BUSY = 1
};
if (Trunk[index].trunk_state == TRUNK_IDLE) // 不建议直接使用Trunk[index].trunk_state == 0
{
Trunk[index].trunk_state = TRUNK_BUSY;
... /* program code */
}
4.4 常用命名缩写
/*
argument 可缩写为 arg
buffer 可缩写为 buff
clock 可缩写为 clk
command 可缩写为 cmd
compare 可缩写为 cmp
configuration 可缩写为 cfg
device 可缩写为 dev
error 可缩写为 err
hexadecimal 可缩写为 hex
increment 可缩写为 inc
initialize 可缩写为 init
maximum 可缩写为 max
message 可缩写为 msg
minimum 可缩写为 min
parameter 可缩写为 para
previous 可缩写为 prev
register 可缩写为 reg
semaphore 可缩写为 sem
statistic 可缩写为 stat
synchronize 可缩写为 sync
temp 可缩写为 tmp
*/