电控组软件编程规范.md

#电控组软件编程规范 ##工程规范

1. 基于Stm32 Cube自动生成的工程树进行;
2. 工程中汉字编码统一选择 ANSI 方式；
3. 每一个新增功能以 XxxxTask 的形式命名，分别保存其源文件和头文件于路径 ...\Tasks\Src和Inc 中，要求 Xxxx 能体现该任务的作用；

##风格规范

1. 对于未完成的代码，在上传至github时，必须添加\\ToDo注释做标记；
2. 缩进统一采用制表符（Tab键），避免使用四个空格；
3. 所有文件结尾处必须空置一行，否则编译会产生Warning；
4. 除if、for等语句在其执行语句极短的情况下，不允许一行书写多句代码；

##文件规范

1. 每个源文件需要存在一个同名头文件，用于声明公开函数接口与全局变量；
2. 除 Cube 生成的文件外，所有文件在其源文件和头文件的开头，需依照附录A中格式留下相应信息；
3. 每个头文件需要添加宏定义保护，格式详见附录B;
4. 非必要 Task 需要增加宏定义选择功能，宏定义标识号需与功能名称保持一致（并为其全大写形式），保证不必要的Task可以选择不被编译；

##宏定义规范

1. 使用宏定义书写的内容，保证其标识为全大写形式；
2. 对于多次使用的常量（出现次数高于一次）（系数、常量等），意义不明显的数据（如：键鼠回传数据中，每个键对应的16bit数据），函数（如：控制GPIO输出的函数）需选用宏定义的方式进行书写，便于统一更改，或增强代码可读性；
3. 宏定义标识符格式见下；

类型	标头	作用对象	常量含义or动作
常量：	CONST__	多词时用单下划线（_）连接	双下划线连接（__）
系数：	COEF__	多词的词数不应超过两个	系数常量等对应前者
函数：	FUNC__	同时善用缩写	函数对应后者

例子：

• #define CONST__UD_MOTOR__STEP 15
• #define COEF__RC_CHASIS__SPEED 1.3
• #define FUNC__LED__LIGHT() HAL_GPIO_WritePin(GPIOF, GPIO_PIN_0,GPIO_PIN_RESET)

##变量，类型命名规范

类型部分

1. 创建一个结构体类型时，其名称需以 _t 结尾；
2. 创建一个枚举类型时，其名称需以 _e 结尾；
3. 类型名采用大驼峰式书写：即用大写区分各单词（特定缩写词应全部大写，如：PID），除结尾外不使用下划线；

例子：

• WorkState_e
• KeyboardMode_e
• MotorINFO_t

变量部分

1. 变量名由对象和变量含义两部分构成，中间使用单下划线（_）分割;
2. 部分内部，采用大驼峰式书写：即用大写区分各单词（特定缩写词应全部大写）；
3. 需要跨文档使用的变量，在变量定义所在文档的同名头文件中做extern操作

例子：

• UDMotor_TargetAngle
• RCChannel_RightColValue

##函数规范

1. 函数定义必须在源文件中，需要跨文档使用的函数，其声明必须在函数定义所在文档的同名头文件中；
2. 在函数开头处需按照附录C的格式书写函数说明；
3. 函数命名要求：

1. 格式：<工具/实现方式> _ <动作> _ <对象> _ <目标量>
2. <>内部内容以大驼峰式书写（特定缩写词照常全部大写）

例子：

Infrared_Read_Distance_Value(); GPIO_Set_RedLED_On();

##附录 ###附录A-文件规范

/*******************************************************************
  * File Name   : XxxxTask
  * Description : 
  * Author      : 
  * Telephone   :
********************************************************************
  *
  * Copyright (c) 2019 Team Jiao Long - ShanghaiJiaoTong University
  * All rights reserved.
  *
*******************************************************************/

###附录B-宏定义保护

#ifndef __XxxxTask_H
#define __XxxxTask_H
   // ..........
   // ...内容...
   // ..........
#endif /*__ XxxxTask_H */

###附录C-函数说明

/*******************************************************************
  * 功能简述        : 
  * 输入输出参数说明 :
  * 作者            ：
  * 联系方式        ：
*******************************************************************/

如果用到复杂的算法，需要添加算法说明（备赛期间可空置，但需要写出，待赛后完成）。

###附录D-常用缩写 默认知道INFO，COL等非常常见的缩写。 （如果后续还有不清楚的信息，再做添加）

示意	全称	缩写
底盘电机	Chassis Motor	CM
云台电机		GM
辅助设备	Auxiliary	AUX
电子调速器	Electronic Speed Controller	ESC
温度	Temperature	temp
临时量	Temporary	tmp
遥控	Remote Control	RC
键鼠	Keyboard Mouse	KM
状态机	Finite State Machine	FSM
信息	Message	Msg
完整	Complete	Cplt
接受	Receive	Rx
发送	Transport	Tx