分析一套源代码的代码规范和风格并讨论如何改进优化代码

本次工程实践我选的题目是基于ESP32开发板进行开发的，其主要使用的语言为c语言。但由于是嵌入式开发，因此还需要编写很多的配置文件以及引入官方提供的SDK进行开发。

一、分析源代码目录结构

　该项目的目录结构很清晰，主要解释如下：

　　（1）.vscode:存放工作区配置文件，如setting.json等

　　（2）build:存放项目构建所必须的库

　　（3）main:存放项目的所有源代码

　　（4）Makefile文件:文件中包含项目的编译信息

　　（5）CMakeLists.txt:存放Cmake编译信息

二、文件名、类名、函数名、变量名等命名

　本项目的各种命名均十分符合命名的规范，使用了Snake Case命名法，单词中间用_分隔，无论是函数名还是变量名、类名、文件名，均采用下划线将单词连接起来，形成词组，通过阅读命名我们即可清楚获知其用途。函数命名如下：

变量命名分为两种，对于普通变量，也采用下划线连接单词的命名方法，如下图：

对于宏定义，命名规则与普通变量命名相同，但是却换成了大写字母，以便于区分，如下：

 

三、接口定义规范　

接口泛指把自己供给外界调用、使用、访问等的一种抽象。本项目的接口定义十分标准，甚至按照一定标准加上了注释。

@brief:该接口的简单介绍，包括功能等信息

@param[in]:该接口的输入变量的要求，包括类型等信息

@return:该接口的返回信息，包括返回类型及其代表含义

四、项目代码风格

本项目的代码风格很好，尤其体现在“空行”上，如函数之间各有空行，变量定义和后续循环控制有空行，等等，代码十分清晰。另外在“空格”上，本项目的也十分优秀，标点与单词之间，括号之间都注意了空格的问题，让看代码的人赏心悦目。

 

五、列举哪些做法有悖于“代码的简洁、清晰、无歧义”的基本原则，及如何进一步优化改进

很多同学在刚学习编程时会形成一些很不好的习惯，其中最突出的是变量命名问题，如通篇命名使用a,b,c等简单字符，容易导致在后续的编程过程中不清楚变量信息，很难进行维护。本项目的命名规则十分优秀，是一个值得学习的模范项目，通过学习本项目的命名规则，我相信后续的编程过程中会养成更好的命名习惯。

六、总结同类编程语言或项目在代码规范和风格的一般要求

在文件排版方面，有以下几点：

　• 先系统头文件，后用户头文件。

　• 系统头文件，稳定的目录结构，应采用包含子路径方式。

　• 自定义头文件，不稳定目录结构，应在dsp中指定包含路径。

　• 系统头文件应用：#include <xxx.h>

　• 自定义同文件应用：#include "xxx.h"

• 只引用需要的头文件。

• 文件头、控制块，#include部分、宏定义部分、class部分、全局常量部分、全局变量部分、函数和函数之间，用两个空行。

在注释方面：

• 关键函数必须写上注释，说明函数的用途。

　• 特别函数参数，需要说明参数的目的，由谁负责释放等等。

　• 除了特别情况，注释写在代码之前，不要放到代码行之后。

　• 对每个#else或#endif给出行末注释。

　• 关键代码注释，包括但不限于：赋值，函数调用，表达式，分支等等。

　• 善未实现完整的代码，或者需要进一步优化的代码，应加上 // TODO …

　• 调试的代码，加上注释 // only for DEBUG

　• 需要引起关注的代码，加上注释 // NOTE …

　• 对于较大的代码块结尾，如for,while,do等，可加上 // end for|while|do

最后还有很重要的，在风格方面：

　• 每一行开始处的缩进只能用Tab，不能用空格，输入内容之后统一用空格。除了最开始的缩进控制用Tab，其他部分为了对齐，需要使用空格进行缩进。这样可以避免在不同的编辑器下显示不对齐的情况。

　• 在代码行的结尾部分不能出现多余的空格。

　• 不要在"::","->","."前后加空格。

　• 不要在"，","；"之前加空格。