软件代码格式规范

正好国庆，整理并且编写下这篇文章来说说编程代码格式规范，使代码更加精简、整洁和清晰。开发人员编写出简洁、可维护、可靠、可测试、高效、可移植的代码。从长远来看，不仅利于别人看懂，也利于代码管理和使用。

一、注释规范

1．新增文件在头部需要添加声明，内容包括有作者、日期、功能描述和基础声明，其他内容可根据实际情况需要添加描述。

/*
* @Author: Yank_k Link
* @Date: 2022-10-01 15:42:46
* @LastEditTime: 2022-10-01 08:42:14（可选）
* @Description: Header file for test.c
* @Note: Copyright (c) 2022, Yank_k Inc., All rights reserved
*/

2．当有较复杂逻辑流程或数学计算流程时，需在最前面使用/**说明**/的方式对这段代码进行说明注释，并在适当位置添加必要的注释。例如：

/****** Temperatures detect and calculate process *****/
while(1){
/*code*/
}
/*****************************************************/

3．在头文件声明的供外部调用函数需在前一行进行必要的注释/功能描述/，用于描述函数的参数、返回值和功能等。
4．普通注释直接使用双斜杠（//）进行注释即可，禁止使用中文或者拼音进行注释说明。

二、命名规范

1．标识符命名
定义标识符要清晰明了，有明确的含义，使用完整的单词或用通用的缩写，避免使人产生误解，禁止使用中文拼音定义。较短单词可以通过去掉“元音”形成缩写，较长单词可以取单词前几个字母形成缩写，常见缩写例子如下：

argument 可缩写为 arg
buffer 可缩写为 buff
clock 可缩写为 clk
command 可缩写为 cmd
configuration 可缩写为 cfg

device 可缩写为 dev
compare 可缩写为 cmp
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
.....

2．变量名
除了循环结构变量可以使用（i、j、n、m）等常用循环变量外，其他禁止使用单个字符（a、b、c、d„…）等意义不明的字符作为变量名
局部变量：函数内局部变量使用小写加下划线的方式进行声明命名，例如：

int tmp, tmp_size;
char name[100];

全局变量：全局变量使用驼峰的方式进行声明，变量前缀用作用域简写来说明
其作用域，作用域简写如下：

全局变量 g_
静态变量 s_
全局静态变量 gs_

int g_EncoderDirectorInfo
static int gs_EncoderDirectorInfo

3．函数名
函数名以“模块+动作+操作对象”的命名方式进行描述，采用两种编码格式进行编写：
（1）小写加下划线的方式：下划线尽量不要超过两个，一般用于外部其他模块的调用

例如：int encoder_get_info(int encoder_name)

（2）采用小驼峰方式：开头为小写后面每个单词首字母用大写，一般用于模块内部调用

例如：int encoderGetInfo(int encoder_name)

4．类型复合类型（结构体、联合、枚举），以“模块名+作用”的命名方式，使用大驼峰或全大写（兼容部门软件架构代码风格）方式命名，例如：

typedef struct
{ . . . . .}EncoderInfo;
typedef enum
{ . . . . .}ENCODERINFO;

5．常量
宏定义、枚举（常量）均采用全大写和下划线的编码方式，以“模块名+描述”的方式命名，例如：

#define ENCODER_INFO_FRAM 1024
enum{ ENCODER_INFO_FRAM};

6．文件名
文件名以“模块+功能”的描述方式进行命名：
（1）小写加下划线方式，例如：

encoder_process_data.c

（2）大驼峰方式，例如：

EncoderProcessData.c

三、编码规范

基础编码规则
（1）禁止使用未初始化的变量作为右值；
（2）禁止使用未初始化的指针，使用指针需要特别注意内存越界问题；
（3）避免重复包含相同的头文件（例如a.h已包含j.h k.h，b.h包含a.h后又声明包含j.h或k.h），禁止头文件循环依赖（例如a.h包含b.h，b.h包含c.h，c.h包含a.h）；
（4）.c/.h禁止包含未使用的头文件；
（5）禁止在头文件里定义变量；
（6）及时清理不使用的代码和变量；
（7）避免在函数内执行不符合函数名描述功能的操作；
（8）函数固定的参数使用const进行声明；
（9）一个变量只能有一个功能，不能把一个变量用于多种用途；
（10）每层代码缩进4个字符（tab），整体有层次感。
模块化结构化管理
（1）对同一功能和类型的功能或驱动，建立模块文件进行描述，模块内针对不同单个功能拆分为不同的函数进行描述。
（2）当模块功能有多个文件时以模块名建立文件夹存放模块代码文件；
（3）函数的参数个数不超过5个；
（4）避免单个函数过长，新增函数一般不超过50行（非空非注释行）；
（5）避免函数套嵌过深，新增代码块的层数一般建议不超过4层；
（6）尽量不用或者少用全局变量，尽量不使用“extern”输出变量和函数接口，改用声明函数的方式获取变量和函数接口；
（7）模块内特性相关的多个变量需要被获取时，定义结构体存放来代替多个变量
（8）在使用if时需要有else分支，所有的switch语句必须有default分支；
（9）对于函数返回的错误码需要有判断或处理，至少有printf打印输出；
（10）重构/修改部分代码时，需要延用原来的代码编程风格进行编写；