前言
对于Python语言,存在Python官方的 PEP-8 规范。C系发展时间早,虽然没有一套官方提出的规范,但是很多编码规范已经形成了共识。
本文提出了一部分代码规范要求,以便代码便于管理和迭代。
Chapter 1. 编码规范
所有文件使用 UTF-8 完成编码。使用KeilμVision5 的六代编译器完成编译。
推荐使用CubeMX+Keil+Vscode的KeilAssitant 编译链
对于已经拥有其他编码的文件,不应改变其编码格式。
注:
使用CubeMX生成工程可能导致UTF-8编码被GBK化从而产生乱码。
为了避免此问题,请参见如下博客:CubeMX生成时产生乱码
Chapter 2. 文件要求
文件名长度应尽可能短的同时完成库功能的描述
文件命名使用小写蛇形命名法
an_name_example.c
文件命名分为两部分:
第一部分:该文件完成的功能,如:motor,pid,led等
第二部分:如果有多种模块完成同一功能,在第一部分后写上模块型号
例:对于两个同样完成电机驱动的库,一个适用于M3508电机,一个适用于M2006电机,则命名分别应该为
motor_m3508.c
motor_m2006.c
Chapter 3. 文件编写规范
作为库文件,应尽可能减少对extern关键字的依赖
不同文件间的沟通应尽可能使用接口函数,而不是直接调用
文件应极力避免使用goto语句
变量名称 使用小蛇形命名法
uart_0_buffer
函数和线程名称 使用小驼峰命名法(首字母小写)
getOdometerData
类、结构体、枚举变量名称 使用大驼峰命名法(首字母大写)
TestObjectState
宏定义、Const常量名称 使用大写蛇形命名法(首字母大写)
UPDATE_TIM_MS
在代码编写的过程中,必须注意每个功能区段间的缩进和换行,使代码整体易于阅读和修改。在必要时,使用括号来提高代码可读性
while(a-->10){if(a>>2>3?1:0)a++;};
while ((a--) > 10)
{
if ((a >> 2) > 3 ? 1 : 0)
a++;
};
如果使用Vscode编程,可以使用 右键-》格式化文档 来完成文档缩进的规范化。
Chapter 4. 注释规范
部分代码注释基于Doxygen规范 进行注释
不要求使用排版符 对所编写的注释进行排版,因为没有生成Doxygen文档的需求;但是有文件可读性的需求。
(1)在编写的文件的开头,使用文件注释
在文件注释中,应标明库的标题、简介、所有作者(后续更改者也添加在author中)、版本、最后更改日期、最后一次改动的内容
/**
* @file test.h
* @mainpage 。。。库
* @brief 用于。。。
* @author 。。。
* @version 1.0
* @date 24-9-1
* @note 新增一个函数。。。新增类。。。修复了bug。。。改动了函数。。。使得。。。
*/
在文件注释的下方,应写明本库的使用方法、注意事项
/**
* @mainpage 使用事项
* @detail 使用本库,应首先。。。接着。。。最后。。。
* @warning xx函数可能会返回意料之外的值;xx类不能被用于xx操作,否则会。。。;不推荐使用。。。操作
*/
(2)在编写的结构体、类和枚举变量的开头,使用类注释
对于一个类、枚举变量或结构体的注释必须包括以下要素:简介、性质、主要用途
类和结构体内部的重要变量也应拥有注释
/**
* @brief 测试类,主要用来演示Doxygen类的注释方式
* @detail 。。。
* @note 。。。
*/
class Test
{
/// @brief 演示变量
int a;
};
(3)在函数的开头,使用函数注释
使用Vscode编程时,Vscode会在连击三下“/”键后自动写出以下内容
函数注释应包含:简介,参数说明,返回值的说明
/// @brief 一个测试函数
/// @param a 参数A
/// @param b 参数B
/// @return A和B若满足。。。条件,返回true
bool test_function(int a, float b);
(4)在重要变量和所有全局标志位的开头,使用变量注释
重要变量使用注释来解释其运作机制;全局标志位必须使用注释来明确其产生的影响和产生影响的位置
/// @brief 用于。。。的停止,为0时。。。,为1时。。。
bool StopFlag;
(5)有必要时,在宏定义的开头,使用宏定义注释
/// @brief 更新时长间隔的毫秒数
#define UPDATE_TIM_MS 10
(6)有必要时,可根据个人喜好,在语句的上方或后方添加普通注释
c = a + b // 叠加a和b