前言:本系列教程旨在如何将自己的代码写的整洁,同时也希望小伙伴们懂如何把代码写脏,以备不时之需,同时本系列参考 正点原子 , 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
上述这些出函数本身带来的信息,是值得去注释的,这些是对于读你代码的人是有用的,是有价值的信息。
#代码缩进问题
使用TAB进行缩进的时候,这个键的值可能是4位或者是8位,有的小伙伴上面缩进4跟下面8个,随便缩进,反正不会报错,看着确实难受,如果使用文本方式打开,驱动文件,可以发现是跟在KEIL5中阅读的缩进大小是不一样的。
如果代码被不同的编译器打开,缩进效果,也是不一样的,但是如果使用 空格键 代替缩进在大多数编译平台看到的区别都是不大的。
这里在KEIL5中是4位缩进,下面使用VSCODE打开相同的源文件
可以看到这里就变成了8位缩进,只是因为使用的编译器不同,导致效果就不一样了,同时附带着汉字乱码(改编码格式)。
总结:如果代码经常移植,建议缩进使用空格代替。
欢迎指正,希望对你有所帮助!!!