auto_bus/docs/代码规范/代码规范.md

代码规范

命名规则

变量命名规则

所有的局部变量都使用小写的下划线命名法。

int bus_position;
char* output_string

在变量命名时应注意尽可能简洁清晰，但在不能为了简洁而导致变量意义的不明。

错误示范：

// DO NOT DO THIS:
lv_indev_drv_t indev_drv;

正确示范：

lv_input_device_driver_t mouse_input;

本例子来自LVGL库。

lv表示这个类型来自LVGL库，input_device表示这个一个输入设备，driver表示这是一个驱动，后缀t表示这是一个类型。

常量命名规则

采用#define定义的常量采用全大写下划线命名法

#define MAX_STR_LENGTH 1000

函数命名规则

所有函数采用驼峰命名法。

int strLength(char* str);

代码风格

缩进

统一使用tab，四个空格的缩进。

#include <stdio.h>

int main()
{
	printf("缩进是四格。\n");
    return 0;
}

这点一般不需要注意，现在流行的IDE都是四格缩进。

大括号

所有的大括号都需要提行书写。

if()
{

}
for()
{

}
int main()
{

}

同时注意在代码中所有的代码块都需要用大括号包裹，即使是一行的情形。

// DO NOT DO THIS
if(1)
	printf("...");
// DO THIS
if(1)
{
	printf("...");
}

注释

采用Doxygen风格的注释

在VSCode中安装Doxygen Documentation Generator这个扩展。

方便使用下列的功能。

在函数，变量的上一行输入/**后回车来创建模板。

/**
 * @brief 在stdin打印一个字符串
 * 
 * @param str 指向需要打印的字符串指针
 */
void print(char* str)
{
    printf("%s", str);
}

#include "example.h"

int main()
{
    /**
     * @brief 需要输出的字符串
     * 
     */
    char* string = "Good morning!\n";
    print(string);
    return 0;
}

在@brief的后面输入函数的作用简述，在@param的输入每个参数的意义， 在@return的后面输入返回值的意义。

在VSCode中将指针悬停在函数上时就可以查看这个注释。

其他的注释都应该放在需要注释行的上一行。

在Doxygen规范中，所有的注释都是注释下一行的代码。

在文件开头的注释不做要求，我感觉应该没有什么用。

这里推荐一个VSCode插件GitLens，可以方便的查看提交信息，便于在发现问题时锤人。

杂项

• 函数中的局部变量不必在函数的头部统一命名，但是建议比较重要的变量在头部先声明，并且使用注释注明变量的作用
• 循环的变量一般情况下都在for语句中声明，不在循环以外的地方使用。但如果较为特殊的地方使用到，请使用注释表明。并且循环变量使用i,j,k。
• switch语句中必须要有default的部分。
• 每行代码不超过80个字符。