关注公众号，回复“入门资料”获取单片机入门到高级开挂教程
开发板带你入门，我们带你飞
文 | 无际（微信:2777492857）
全文约6352字，阅读大约需要 10 分钟
你有没有过这样的经历？
刚入职一家公司，兴致勃勃地打开项目代码，准备大干一场，结果：
变量名是 a、b、tmp，函数名是 func1、process，参数列表密密麻麻，不知道传进去的是什么鬼。
宏定义和常量散落在文件的各个角落，想改个参数得全文件搜索。
同一个逻辑，一会儿用 if else，一会儿用 switch case，一会儿又来个 goto。
代码块的缩进，大括号一会儿在行尾，一会儿在新行，风格随机切换。
最要命的是，注释呢？它在哪里？哦，找到了，一行 // 初始化 孤零零地立在那，告诉你这行代码是用来初始化的，而你早就知道它干的是初始化的活，但它具体初始化了啥，为啥这么初始化，背景信息一概没有。
你瞪大了双眼，感觉不是在读代码，而是在破前任的案。心里的骂骂咧咧：这到底是哪位大神的杰作？是想考验我的智商还是耐心？
别装了，我知道你懂。甚至，你可能正在挠头想，我写的代码，在别人眼里会不会也是这样？
以上，我们每个人或多或少都遇到过，或者制造过的。
别小看这些写代码的小习惯、小毛病。它们积累起来，就像雪球一样，越滚越大，最终可能压垮整个项目。
当你的代码难以阅读时，调试效率，维护成本，稳定性等等都原地爆炸。
这玩意，就跟停车一样的，作为老司机，我一向方便别人，就是方便自己。
同样，规范化编程不仅仅是为了让代码看起来漂亮，更是为了提升效率、降低成本、保障质量、促进协作，最终成就更好的产品和更优秀的自己。
通过这篇文章，你将Get到：
•一套行之有效的单片机C语言编程规范指南。
•理解为何这些规范至关重要。
•掌握写出清晰、易读、易维护代码的秘诀。
•学会如何通过代码展现你的专业性，让你的同事在review你的代码时眼前一亮，发自内心地为你点赞！
系好安全带，发车！
1. 命名规范
名字是代码的身份证。好的命名能让你一眼看穿代码的意图，坏的命名则让你抓狂。
1.1 变量名： 使用描述性强的英文单词或缩写，体现变量的用途和类型。采用驼峰命名法或下划线命名法，并在团队内统一。局部变量可以用较短的名称，全局变量和静态变量需要更长的、带有前缀的名称。
￮示例：int sensor_value; (下划线) 或 int sensorValue; (驼峰)
￮避免：int val;, int tmp;
1.2 常量（宏定义 #define 或 const）：全部大写，单词之间用下划线分隔。体现常量的含义。
￮示例：#define MAX_BUFFER_SIZE 256, const int MOTOR_SPEED_HIGH = 1000;
￮避免：#define SIZE 256, const int highSpeed = 1000;
1.3 函数名： 使用动词或动宾短语，体现函数的功能。采用驼峰命名法或下划线命名法，与变量名风格一致。
￮示例：void init_system(void); 或 void initSystem(void);, int read_sensor_data(void); 或 int readSensorData(void);
￮避免：void init();, int getData();, void process();
1.4 枚举类型（enum）和结构体类型（struct）：使用有意义的名称，通常首字母大写，或加特定前缀（如 e_，s_）。枚举成员全部大写，单词之间用下划线分隔。
￮示例：typedef enum { STATE_IDLE, STATE_RUNNING, STATE_ERROR } e_system_state;
￮示例：typedef struct { uint16_t voltage; uint16_t current; } s_sensor_data;
很多人可能和我一样，英语不好，如果每个细节都这样做，太耗时间了，能按时完成任务都不错了。
以前你这样说，我非常理解你，因为我也是这样干的，哪有精力管这么多。
不过现在有AI的帮忙，几分钟就搞定了，你可以先写个初步的，然后让AI按照命名规则帮你优化变量名、常量、函数名，效率起飞又规范。
2. 代码排版
整洁的排版能大幅提升代码的可读性。
缩进： 使用空格进行缩进，不建议使用Tab（因为Tab在不同编辑器显示宽度不同）。通常使用4个空格作为一个缩进级别，并在团队内强制统一。
大括号 {}：采用Allman风格，即左大括号 { 放在新的一行，与对应的关键字（如 if, for, while, 函数名）对齐。右大括号 } 也独占一行，与左大括号对齐。
￮示例：
空行： 使用空行分隔不同的逻辑块、函数定义、变量声明等，增加代码的层次感和可读性。
空格： 在运算符两侧、逗号后、类型转换后添加空格，例如 a = b + c;, func(arg1, arg2);, (uint8_t)value;。
3. 注释：代码的向导
好的注释不是越多越好，而是恰到好处，能解释清楚代码的“为什么”和“是什么”，而不是简单复述“怎么做”。
•文件头部注释： 包含文件名、作者、创建日期、版本信息、文件功能简述等。
•函数头部注释： 说明函数的功能、参数（名称、含义、取值范围）、返回值（含义、可能的值）、可能的副作用、函数调用时的注意事项等。
•关键代码块注释： 对于复杂的逻辑、巧妙的实现、潜在的陷阱，或者与硬件紧密相关的操作，要添加解释性注释。
•常量和宏注释： 说明其用途和含义。
•避免： 无意义的注释，例如 i++; // i自增1。
•代码示例：
/** 文件名: sensor_module.h* 作者: 无际单片机编程* 创建日期: 2025-4-21* 版本: 1.0* 描述: 提供与传感器模块交互相关的函数和定义。* 主要包括传感器初始化、数据读取和状态获取功能。*/#ifndef __SENSOR_MODULE_H__ // 防止头文件被重复包含的宏定义#define __SENSOR_MODULE_H__#include// 包含标准整数类型定义 /** @brief 定义传感器数据状态的枚举类型*/typedef enum{SENSOR_STATUS_OK = 0, // 传感器工作正常SENSOR_STATUS_ERROR_INIT, // 传感器初始化失败SENSOR_STATUS_ERROR_READ // 传感器数据读取失败// 可以根据实际情况添加更多状态} e_sensor_status;/** @brief 定义传感器原始数据结构体*/typedef struct{uint16_t raw_value; // 传感器原始ADC值或其他原始数据// 根据传感器类型可以添加更多字段} s_sensor_raw_data;/** @brief 定义处理后的传感器数据结构体*/typedef struct{float processed_value; // 例如，转换为实际物理量的数值// 根据需求可以添加更多字段} s_sensor_processed_data;/** @brief 初始化传感器模块* @param 无* @return e_sensor_status: 初始化结果状态* @retval SENSOR_STATUS_OK: 初始化成功* @retval SENSOR_STATUS_ERROR_INIT: 初始化失败*/e_sensor_status sensor_init(void);/** @brief 从传感器读取原始数据* @param raw_data_ptr: 指向存储原始数据的结构体的指针* @return e_sensor_status: 数据读取结果状态* @retval SENSOR_STATUS_OK: 读取成功* @retval SENSOR_STATUS_ERROR_READ: 读取失败*/e_sensor_status sensor_read_raw_data(s_sensor_raw_data *raw_data_ptr);/** @brief 处理传感器原始数据，转换为可用数值* @param raw_data: 传感器原始数据结构体* @param processed_data_ptr: 指向存储处理后数据的结构体的指针* @return e_sensor_status: 数据处理结果状态 (通常处理不涉及硬件，总是成功，但仍返回以保持接口一致性)* @retval SENSOR_STATUS_OK: 处理成功*/e_sensor_status sensor_process_data(const s_sensor_raw_data *raw_data, s_sensor_processed_data *processed_data_ptr);/** @brief 获取当前传感器模块的状态* @param 无* @return e_sensor_status: 当前传感器模块的运行状态*/e_sensor_status sensor_get_status(void);#endif // __SENSOR_MODULE_H__
/** 文件名: sensor_module.c* 作者: 无际单片机编程* 创建日期: 2025-4-21* 版本: 1.0* 描述: 传感器模块的实现文件。包含硬件初始化、数据采集和处理逻辑。*/// 全局变量：存储传感器模块的当前状态，使用g_前缀表示全局static e_sensor_status g_current_sensor_status = SENSOR_STATUS_ERROR_INIT;/** @brief 初始化传感器模块* @param 无* @return e_sensor_status: 初始化结果状态* @retval SENSOR_STATUS_OK: 初始化成功* @retval SENSOR_STATUS_ERROR_INIT: 初始化失败** @note 该函数会配置传感器相关的GPIO、ADC通道等硬件资源。* 如果硬件配置失败，则返回错误状态。*/e_sensor_status sensor_init(void){e_sensor_status status = SENSOR_STATUS_ERROR_INIT;// TODO: 调用硬件抽象层函数进行传感器硬件初始化// 假设这里调用了HAL库或者底层的驱动函数if (HAL_Sensor_Init() == HAL_OK){// 硬件初始化成功后，设置模块状态为OKg_current_sensor_status = SENSOR_STATUS_OK;status = SENSOR_STATUS_OK;// 重要代码块注释：初始化完成后进行一次传感器自检，确保工作正常if (HAL_Sensor_SelfTest() != HAL_OK){g_current_sensor_status = SENSOR_STATUS_ERROR_INIT; // 自检失败，更新状态status = SENSOR_STATUS_ERROR_INIT;// TODO: 记录错误日志或者触发报警}}else{// 硬件初始化失败g_current_sensor_status = SENSOR_STATUS_ERROR_INIT;status = SENSOR_STATUS_ERROR_INIT;// TODO: 记录错误日志或者触发报警}return status;}/** @brief 从传感器读取原始数据* @param raw_data_ptr: 指向存储原始数据的结构体的指针* @return e_sensor_status: 数据读取结果状态* @retval SENSOR_STATUS_OK: 读取成功* @retval SENSOR_STATUS_ERROR_READ: 读取失败** @note 读取前会检查传感器当前状态。如果状态异常，则不执行读取操作。* 读取完成后会将读取到的原始值存入指定的结构体。*/e_sensor_status sensor_read_raw_data(s_sensor_raw_data *raw_data_ptr){// 参数有效性检查，虽然简单的例子可以省略，但在实际项目中很重要if (raw_data_ptr == NULL){// TODO: 处理空指针错误，例如断言或者返回错误码return SENSOR_STATUS_ERROR_READ; // 或者定义一个专门的参数错误状态}// 关键判断注释：只有当传感器状态正常时才尝试读取数据if (g_current_sensor_status != SENSOR_STATUS_OK){// printf("Sensor not in OK state, cannot read.\n"); // 调试信息，实际单片机可省略或用Log替代return SENSOR_STATUS_ERROR_READ; // 传感器状态异常，返回读取失败}uint16_t adc_value = 0;e_sensor_status status = SENSOR_STATUS_ERROR_READ;// TODO: 调用硬件抽象层函数从ADC读取原始值// 假设HAL_ADC_Read() 返回ADC值，失败返回特定的错误值或通过返回值检查if (HAL_ADC_Read(&adc_value) == HAL_OK) // 假设HAL_ADC_Read有返回值指示成功或失败{raw_data_ptr->raw_value = adc_value;status = SENSOR_STATUS_OK;}else{// 读取硬件失败g_current_sensor_status = SENSOR_STATUS_ERROR_READ; // 更新模块状态为读取失败status = SENSOR_STATUS_ERROR_READ;// TODO: 记录错误日志或者触发报警}return status;}/** @brief 处理传感器原始数据，转换为可用数值* @param raw_data: 传感器原始数据结构体* @param processed_data_ptr: 指向存储处理后数据的结构体的指针* @return e_sensor_status: 数据处理结果状态 (通常处理不涉及硬件，总是成功，但仍返回以保持接口一致性)* @retval SENSOR_STATUS_OK: 处理成功** @note 该函数执行线性转换或其他复杂的算法，将原始ADC值转换为实际物理量。* 例如，将ADC值转换为电压、温度、湿度等。*/e_sensor_status sensor_process_data(const s_sensor_raw_data *raw_data, s_sensor_processed_data *processed_data_ptr){// 参数有效性检查if (raw_data == NULL || processed_data_ptr == NULL){// TODO: 处理空指针错误return SENSOR_STATUS_ERROR_READ; // 或定义专门的参数错误状态}// 关键算法注释：将12位ADC原始值（范围0-4095）转换为电压值（假设参考电压3.3V）// 公式: Voltage = (ADC_Value / 4095.0) * 3.3Vconst float ADC_MAX_VALUE = 4095.0f; // 使用命名常量代替魔术数字，并添加注释说明含义const float REFERENCE_VOLTAGE = 3.3f; // 参考电压值processed_data_ptr->processed_value = ((float)raw_data->raw_value / ADC_MAX_VALUE) * REFERENCE_VOLTAGE;// TODO: 如果需要更复杂的转换（例如，非线性、查表），在此实现并添加详细注释说明算法或公式。return SENSOR_STATUS_OK; // 数据处理通常不会失败，除非输入参数无效}/** @brief 获取当前传感器模块的状态* @param 无* @return e_sensor_status: 当前传感器模块的运行状态*/e_sensor_status sensor_get_status(void){return g_current_sensor_status;}// 假设的硬件抽象层函数声明，实际应在 hardware_abstraction.h 中定义/*HAL_OK: 假设的硬件操作成功返回值HAL_ERROR: 假设的硬件操作失败返回值*/typedef int HAL_StatusTypeDef; // 假设HAL状态类型是intHAL_StatusTypeDef HAL_Sensor_Init(void); // 初始化硬件HAL_StatusTypeDef HAL_Sensor_SelfTest(void); // 传感器自检HAL_StatusTypeDef HAL_ADC_Read(uint16_t *value); // 从ADC读取值// 假设这些函数有简单的实现，以便编译示例HAL_StatusTypeDef HAL_Sensor_Init(void) { /*printf("HAL: Initializing sensor...\n");*/ return HAL_OK; }HAL_StatusTypeDef HAL_Sensor_SelfTest(void) { /*printf("HAL: Sensor self-test...\n");*/ return HAL_OK; } // 或返回HAL_ERROR模拟失败HAL_StatusTypeDef HAL_ADC_Read(uint16_t *value) { /*printf("HAL: Reading ADC...\n");*/ if (value) *value = 2048; return HAL_OK; } // 模拟读取一个值
4. 函数
函数是构建程序的模块。
•单一职责原则： 一个函数只做一件事情，并把它做好。函数功能越单一，就越容易理解、测试和重用。
•控制函数长度： 尽量保持函数简短，理想情况下一个函数不超过一屏幕。过长的函数往往意味着它做了太多事情，可以考虑拆分成更小的函数。
•明确的接口： 函数参数和返回值应清晰地表达输入和输出。避免使用全局变量作为函数的主要输入或输出。
•代码示例：
// 定义一些常量，符合命名规范，用于电压转换计算const uint16_t ADC_MAX_VALUE = 4095; // 假设ADC是12位的，最大值为2^12 - 1const float REFERENCE_VOLTAGE = 3.3f; // 假设ADC的参考电压是3.3V/** @brief 从传感器硬件读取原始ADC值* @details 这个函数只负责与底层硬件交互，获取原始的ADC数值。* 它不知道这个值代表什么物理量，也不进行任何转换。* @param 无* @return uint16_t: 读取到的原始ADC值*/uint16_t sensor_read_raw_adc(void){// TODO: 这里模拟从硬件ADC通道读取原始数据// 实际代码会调用底层驱动或HAL库函数，例如：// uint16_t raw_value = HAL_ADC_GetValue(ADC_CHANNEL_SENSOR);// 假设读取硬件可能失败，但为了示例简洁，这里省略复杂的错误处理和返回值检查// 实际应用中需要检查硬件读取函数的返回值并处理错误uint16_t raw_value = 2048; // 模拟读取到的一个中间值，例如参考电压的一半return raw_value;}/** @brief 将原始ADC值转换为实际电压值* @details 这个函数只负责执行数学计算，将原始ADC数据按照特定公式转换为电压。* 它不负责读取硬件，也不负责后续的数据使用（如打印）。* @param raw_adc_value: uint16_t 类型的原始ADC值* @return float: 转换后的电压值 (单位V)*/float sensor_convert_adc_to_voltage(uint16_t raw_adc_value){// 参数校验：确保输入值不超过ADC最大值，避免潜在的转换问题if (raw_adc_value > ADC_MAX_VALUE){// 可以选择记录警告、返回一个特殊值（如NaN）或限制输入// 为了示例简单，这里直接限制输入值raw_adc_value = ADC_MAX_VALUE;}// 执行转换计算： 电压 = (原始值 / 最大原始值) * 参考电压// 使用浮点数进行精确计算float voltage = ((float)raw_adc_value / ADC_MAX_VALUE) * REFERENCE_VOLTAGE;return voltage;}/** @brief 完成传感器数据采集、转换并报告的任务流程* @details 这个函数作为一个协调者，依次调用读取原始数据和转换数据的函数，* 然后将最终结果进行报告（例如打印到控制台）。* 它不关心底层硬件细节，也不关心具体的转换公式。* @param 无* @return 无*/void sensor_process_and_report_voltage(void){// 步骤1: 调用负责读取原始数据的函数// sensor_read_raw_adc() 函数隐藏了底层硬件读取的复杂性uint16_t raw_data = sensor_read_raw_adc();// 步骤2: 调用负责数据转换的函数// sensor_convert_adc_to_voltage() 函数隐藏了原始数据到电压的转换公式float voltage_value = sensor_convert_adc_to_voltage(raw_data);// 步骤3: 报告最终的处理结果// 在实际单片机应用中，这里可能是将值发送到UART、更新LCD显示、存储到内存等// 这里使用printf作为示例报告方式printf("Sensor Raw ADC: %u, Converted Voltage: %.2f V\n", raw_data, voltage_value);// TODO: 根据电压值做进一步的逻辑判断或控制输出，例如判断是否超限// if (voltage_value > VOLTAGE_UPPER_THRESHOLD) { trigger_warning(); }}// 一个简单的main函数来演示调用过程 (在单片机中通常是while(1)主循环调用任务函数)int main(void){// 在一个典型的单片机应用中，这里会有系统、外设的初始化调用// 例如：System_Init(); HAL_ADC_Init(); etc.printf("Starting sensor data processing example...\n");// 调用负责整个任务流程的函数// sensor_process_and_report_voltage() 函数是整个任务的入口sensor_process_and_report_voltage();printf("Sensor data processing finished.\n");// 在嵌入式系统中，main函数通常不会返回，而是进入一个无限循环或操作系统调度// while(1);return 0; // 为了在标准PC环境下编译运行示例，这里保留return 0}
5. 变量：按需分配，谨慎使用全局
•局部变量优先： 优先使用局部变量，它们的生命周期和作用域都在函数内部，更容易管理，也能减少不同函数间的耦合。
•谨慎使用全局变量： 全局变量可能在程序的任何地方被修改，导致难以追踪问题。如果必须使用全局变量，考虑加上特定的前缀（如 g_）或使用 static 限制其作用域在当前文件内。
•变量声明位置： 在函数或代码块的开头声明变量，并在声明时初始化。
6. 消灭一切神秘数字
代码中突然出现的数字（如 if (state == 5), delay_ms(100); 这里的 5 和 100）被称为神秘数字，它们让代码难以理解和修改。
•使用命名常量或宏定义： 用有意义的名称代替魔术数字。
￮示例：#define STATE_PROCESSING 5, #define DELAY_SHORT_MS 100
￮使用：if (state == STATE_PROCESSING), delay_ms(DELAY_SHORT_MS);
•使用枚举类型： 对于一组相关的整数常量，使用 enum 是更好的选择。
7. 头文件：干净整洁的接口定义
•包含保护（Include Guards）： 在每个头文件开头使用 #ifndef, #define, #endif 来防止头文件被重复包含。
￮示例：
•只包含必要的头文件： 在 .c 文件中，只包含它需要的头文件。在 .h 文件中，只包含定义了其中声明的类型、常量或函数签名的头文件。避免不必要的依赖。
8. 错误处理与断言
•返回值检查： 对于可能失败的函数调用，检查其返回值，并采取相应的错误处理措施。
•断言（assert）： 在开发和调试阶段，使用 assert 来检查不可能发生的情况或函数的前提条件。如果在运行时断言失败，程序会终止，帮助你快速定位问题。在发布版本中通常会关闭断言。
这个在esp32代码库其实有大量的应用，特别是对于一些指针，内存分配等等。
9. 控制结构
•避免过多的嵌套： 尽量减少 if-else 或循环的嵌套层数，超过三层就需要警惕，考虑提取函数。
•谨慎使用 goto： goto 语句容易破坏代码的线性流程，使代码难以理解和维护。只有在少数特定场景（如跳出多重循环、统一的错误出口）下才考虑使用，并务必谨慎。
咱们写的每一行代码，不仅仅是为了实现功能，更是你专业素养的体现。规范的代码，是工程师之间无声的交流，也是留给未来自己最好的礼物。
end
下面是更多无际原创的个人成长经历、行业经验、技术干货。
1.电子工程师是怎样的成长之路？10年5000字总结
2.如何快速看懂别人的代码和思维
3.单片机开发项目全局变量太多怎么管理？
4.C语言开发单片机为什么大多数都采用全局变量的形式？
5.单片机怎么实现模块化编程？实用程度让人发指！
6.c语言回调函数的使用及实际作用详解
7.手把手教你c语言队列实现代码，通俗易懂超详细！
8.c语言指针用法详解，通俗易懂超详细！
