嵌入式应用开发之代码整洁之道

news2024/11/15 10:33:26

前言：本系列教程旨在如何将自己的代码写的整洁，同时也希望小伙伴们懂如何把代码写脏，以备不时之需，同时本系列参考正点原子， C++代码整洁之道，编写可读的代码艺术。

#好的代码的特点

好的代码应该都有着几条特性，可读性高（根据函数命名就知道这个函数是干啥的），简单（没有复杂的变量英文名，大量调用库中封装函数）。

方便维护（别人在你的代码上加功能好加，好上手），好移植（头文件大量书写宏定义移植只需要改宏定义引脚即可），函数功能单一精简（函数定义几百行，参数很多，永远没有十几行函数代码的好理解）。

调用函数库统一，(没有二次封装函数，没有带位操作跟库函数混着用)，没有带位操作，（程序中统一调用库函数）带位操作确实快，现对于库函数，但是不好上手，没有重新编写函数（如果放着现有的库函数不用，重新赋值寄存器，写新函数，还没有根据功能命名）

上述的这些都是，好的代码的特点，接下来将从，每个类型的变量书写规范开始讲解。

#函数的命名

函数的命名，应该把信息或者注释装进命名里面，同时每个单词使用下划线 "_" 进行连接，，让在读函数命名的同时，就知道你这个函数是什么作用，什么功能，大致看一下函数体，就行了。

void SPI_GPIO_Init(void);

这个函数名，即使不看函数体，也知道这个函数用来将 SPI通信用到的GPIO 初始化，那么如何将代码命名进行规范化。

翻译命名：将这个函数的功能，翻译成英文在命名里面加入英文的缩写，去表示。

外设命名：如果用到对应的外设，可以在命名中加入所用到的外设。

寄存器命名：这个函数里面用到了什么寄存器，什么参数也能写到函数名里面。

#代码注释写给别人看也写给自己看

代码注释不仅仅可以，用来解释这一行代码什么意思做了什么，最重要的是让读你代码的人知道你的写码思想，你此时在关联什么，你在想什么，你要用这些代码去干什么，完成什么，

当自己编写代码的时候，肯定知道自己写这些代码是为了完成什么功能，去怎么应用在需求上，别人读代码，只有眼前每行代码的作用，注释在这个时候，可以是思维，可以是目的。可以是关联应用。

#什么不需要注释

注释在程序中，并不是越多越好的，大量的注释无关紧要的地方，会造成浪费时间，去阅读这些注释，占用屏幕空间，这些注释相对来说是没有价值的。

void Usart_GPIO_Init(void){
    GPIO_InitTypeDef GPIO_InitStructure;//声明结构体变量	

	RCC_AHB1PeriphClockCmd(RCC_AHB1Periph_GPIOA,ENABLE);//开启时钟	

	GPIO_PinAFConfig(GPIOA,GPIO_PinSource9,GPIO_AF_USART1);//开启复用功能
	GPIO_PinAFConfig(GPIOA,GPIO_PinSource10,GPIO_AF_USART1);

	GPIO_StructInit(&GPIO_InitStructure);
	GPIO_InitStructure.GPIO_Pin           = GPIO_Pin_9;//TX引脚
	GPIO_InitStructure.GPIO_Mode          = GPIO_Mode_AF;//IO口用作串口引脚要配置复用模式
	GPIO_InitStructure.GPIO_Speed         = GPIO_Speed_100MHz;//选择速度
	GPIO_InitStructure.GPIO_OType         = GPIO_OType_PP;//推挽输出
	GPIO_InitStructure.GPIO_PuPd          = GPIO_PuPd_UP;
	GPIO_Init(GPIOA,&GPIO_InitStructure);

	GPIO_StructInit(&GPIO_InitStructure);
	GPIO_InitStructure.GPIO_Pin           = GPIO_Pin_10;//RX引脚
	GPIO_InitStructure.GPIO_Mode          = GPIO_Mode_AF;//IO口用作串口引脚要配置复用模式
	GPIO_InitStructure.GPIO_Speed         = GPIO_Speed_100MHz;//选择速度
	GPIO_InitStructure.GPIO_OType         = GPIO_OType_PP;
	GPIO_InitStructure.GPIO_PuPd          = GPIO_PuPd_UP;//推挽输出
	GPIO_Init(GPIOA,&GPIO_InitStructure);
}

上述这些注释是没有价值的，为什么，因为没有提供额外的信息，这些作用能从函数里面读出来，就可以不用去加，写这么多注释是会影响效率的。

总结：不要为代码本身能读出来的信息写注释

同时不要为了写注释，而去注释，总有小伙伴认为，一定要写注释，为了写注释去写注释，从而忽略了写注释本身的作用，写注释是为了更好的理解工程，而不是写没有意义的注释，浪费读你注释的人的时间。

#什么需要注释

注释本身就是一种信息，这种信息不是关于函数功能的信息，这些信息可以加入见解，可以使各种有关经验之谈，可以是别人不知道代码的瑕疵，缺陷，也可以是站在读你代码的人角度写注释，或者解释为什么选择A方案，而不是B方案。

#ifndef  _pid_h_
#define  _pid_h_
#include <stdio.h>
#include "board.h"
//编写PID应在云台中调用
#define Kp  5.0
#define Ki  5.0
#define Kd  5.0
//这里参数设定有问题，云台抖动
typedef struct 
{
    float Velcity_Kp;
    float Velcity_Ki;
    float Velcity_Kd;
    float Error;
    float Last_Error;
    float integral;
    float derivate;
      int Control_Velocity;
}PID;
void PID_Init(PID*pid, float Velcity_Kp ,float Velcity_Ki,float Velcity_Kd);
float PID_Calculate (PID*pid,float Current_Velocity ,float TargetVelocity);
#endif

上述这些出函数本身带来的信息，是值得去注释的，这些是对于读你代码的人是有用的，是有价值的信息。