GD32实战1__编程规范

只看该作者 · 2021-11-30 12:21

目的
规范是经验的积累，需要慢慢用心去体会。

规范
1. 原则
简洁明了，提高代码可读性，读的是代码而不是注释，注释永远都是辅助的。
零告警，严谨的语法才能保障代码表达和编译器理解的是一至的。
2. 排版
缩进4空格，杜绝tab键
程序块之间、变量声明之间，用空行分隔
突出语法关键字
一行不要太长，换行增加可读性
3. 注释
注释的目的是阐明意图目的，而不是翻译某行代码的动作
注释的原则是尽量代码自注释，代码越清晰，可读性越高
统一格式 /* 注释内容 */， *号与注释内容之间有一个空格

只看该作者 · 2021-11-30 12:21

4. 定义
命名风格

模块名+文件名+功能描述，之间采用短下划线分隔
功能描述部分，采用驼峰风格
例如，

复制

VOID OS_TASK_TaskDelay(IN U16 ms);

只看该作者 · 2021-11-30 12:22

宏定义

define 必须大写
typedef 可以小写
例如，

复制

#define OS_TASK_SWITCH_INTERVAL 10 /* 单位ms */

typedef U32 StackSize_t；  /* 仅用于堆栈 */

只看该作者 · 2021-11-30 12:22

类型定义

统一使用下面的，编程最关心符号位和位宽

复制

#define U8  unsigned char

#define S8  char

#define U16 unsigned short

#define S16 short

#define U32 unsigned int

#define S32 int

#define U64 unsigned long long

#define S64 long long

#define VOID void

#define BOOL unsigned char



#define TRUE 1

#define FALSE 0

#define NULL 0

只看该作者 · 2021-11-30 12:23

5. 变量
局部变量
在函数开始是全部定义，不允许在函数中间定义
命名必须能传达该变量使用的意图
必须初始化
全局变量
在C文件中，函数之前统一定义
命名必须能传达该变量的使用意图，且以g开头
本地全局变量必须用static关键字
开发给外部使用的全局变量，必须在头文件中声明，且使用extern关键字
必须初始化

只看该作者 · 2021-11-30 12:24

6. 函数
函数名必须能够自注释，必要是需要增加注释写明意图
参数必须使用IN、OUT、INOUT指明出入参类型
内部函数必须使用static定义，命名可以不加模块名
外部函数
必须在头文件中声明，
必须使用extern关键字，
命名时必须带模块名，
必须给出带注释，并写明函数意图，参数说明，返回值

只看该作者 · 2021-11-30 12:25

7. 文件
头文件

命名规则模块名+功能，小写，例如os_task.h

格式如下
#ifndef __OS_TASK_H__
#define __OS_TASK_H__

..../* 开放的宏定义 */
..../* 开放的全局变量声明 */
..../* 开放的函数声明 */

#endif

只看该作者 · 2021-11-30 12:26

源文件

命名规则模块名+功能，小写，例如os_task.c

格式如下，举例只为说明源文件中，各元素的顺序

只看该作者 · 2021-11-30 12:26

复制

<- 1 - 引用头文件 ->

#include "os_task.h"



<- 2 - 定义本文件用到的宏 ->

#define OS_TASK_SWITCH_INTERVAL 10 /* 单位ms */

typedef U32 StackSize_t ；  /* 仅用于堆栈 */

typedef enum{};

typedef struct{};



<- 3 - 静态全局变量 ->

static StackSize_t *gTopStack = NULL；



<- 4 - 本模块开放的全局变量 ->

U32 gOsTaskEventBitMap = 0; 



<- 5 - 本地函数，仅在本文件使用 ->

static VOID TASK_TaskSwitch(VOID)

{

    return；

}



<- 6 - 本模块开放的函数 ->

VOID OS_TASK_TaskDelay(IN U16 ms)

{

         return；   

}

只看该作者 · 2021-11-30 12:27

8. 模块
模块必须具有封装性，且对外提供尽量少的必要接口，接口必须提供详细的注释描述

模块的组织形式可以是文件夹形式，也可以是文件形式

例如：

只看该作者 · 2021-11-30 12:27

复制

.

├── app /* 应用层代码 */

│   ├── app.h 

│   ├── main.c /* 应用入口 */

│   ├── test.c

│   └── test.h

├── driver /* 设备驱动代码 */

│   ├── drv_led.c

│   ├── drv_led.h

│   ├── drv_uart.c

│   └── drv_uart.h

├── os  /* 操作系统代码 */

│   ├── os_task.c

│   ├── os_task.h

│   └── os_type.h

├── sdk /* 芯片厂家提供的库代码 */

│   ├── CMSIS

│   └── Peripherals