4、命名规范：标识符命名规则与命名风格

嵌入式C语言工程中，命名规范是代码可读性、可维护性和团队协作效率的基石。与纯软件项目不同，嵌入式代码往往直接面向寄存器、硬件外设、中断服务程序以及实时操作系统（RTOS）任务，命名不当不仅会引发理解歧义，还可能导致误操作硬件资源或掩盖潜在的并发问题。本章将系统阐述变量、函数、宏、类型、文件五大类标识符的命名规则，深入对比匈牙利命名法与下划线风格（Unix/Linux风格）的适用场景，并通过正反案例拆解，帮助开发者建立一套统一、严谨且可落地的命名体系。

上图展示了嵌入式命名规范的整体框架。在实际工程中，命名风格的选择往往取决于团队历史代码库、目标编译器特性以及行业惯例（如AUTOSAR、MISRA C）。但无论采用何种风格，可读性、一致性和可搜索性始终是最高优先级。下面我们将逐一拆解各类标识符的具体规则。

4.1 变量命名规则

4.1.1 核心原理：变量名是“数据契约”

变量名应直接反映其存储的数据类型、作用域和业务含义。在嵌入式环境中，变量常与硬件寄存器、中断标志或DMA缓冲区关联，命名不当会直接导致维护者误解数据来源。例如，一个保存ADC采样值的变量，若命名为temp，在代码评审时很难判断其单位是电压、温度还是原始码值。正确的做法是使用前缀+含义+单位后缀的结构。

4.1.2 判断方法：三步命名法

1. 确定作用域：全局、静态、局部，决定是否加前缀。
2. 明确数据类型与业务含义：是计数器、标志位、缓冲区还是句柄？
3. 附加单位或约束：如_ms、_cnt、_max，避免歧义。

4.1.3 案例拆解：ADC多通道采集变量命名

假设一个STM32项目需要采集4路ADC通道，并计算平均值。初始代码中变量命名为a、b、c、d，导致后续维护时无法区分通道。重构后采用如下命名：

/* 重构前 */
uint16_t a, b, c, d;
/* 重构后 */
#define ADC_CH_NUM  (4U)
static uint16_t s_adc_raw[ADC_CH_NUM];      /* 原始值数组 */
static uint16_t s_adc_filtered[ADC_CH_NUM]; /* 滤波后值 */
uint32_t g_adc_sum;                          /* 总和，用于求平均 */
uint16_t g_adc_average;                      /* 平均值 */

重构后，通过s_adc_raw[2]即可明确知道是第3通道的原始值，且s_前缀表明其为模块私有，防止外部误访问。

4.2 函数命名规则

4.2.1 核心原理：动词开头，体现行为

函数名应清晰表达其执行的操作。嵌入式驱动函数通常采用模块名_动词_宾语的结构。例如，I2C读写函数命名为i2c_read_byte()、i2c_write_byte()，比read()、write()更具辨识度。中断服务函数（ISR）应明确标注_isr后缀，如uart1_rx_isr()，以区别于普通回调函数。

4.2.2 操作流程：函数命名检查清单

• 是否以动词或动词短语开头？（get、set、init、deinit、enable、disable）
• 是否包含操作对象？（adc、timer、gpio）
• 返回值类型是否在命名中体现？（如is_前缀表示返回布尔值）
• 是否避免使用否定形式？（如not_ready应改为is_busy）

4.2.3 实战场景：驱动层函数命名对比

4.3 宏与常量命名规则

4.3.1 核心原理：全大写+下划线分隔

宏定义和枚举常量必须使用全大写字母，单词间用下划线分隔。宏名应体现其数值含义或配置用途。例如，#define ADC_SAMPLE_TIME_US (10U)比#define TIME 10更具可读性。同时，宏定义应使用括号包裹表达式，避免运算符优先级问题。

/* 正确示例 */
#define PWM_FREQ_HZ        (1000U)
#define PWM_DUTY_MAX       (1000U)
#define TIMEOUT_MS         (5000U)
/* 错误示例 */
#define FREQ 1000
#define DUTY 1000

4.3.2 判断方法：宏与枚举的选择

当需要定义一组相关常量时，优先使用typedef enum而非多个#define。枚举具有类型检查优势，且便于调试器显示符号名称。例如：

typedef enum {
    ADC_CH_0 = 0U,
    ADC_CH_1,
    ADC_CH_2,
    ADC_CH_3,
    ADC_CH_MAX
} adc_ch_t;

4.3.3 常见误区：魔法数字

直接在代码中书写数字（如if (data > 100)）是嵌入式项目的大忌。应使用宏或枚举替代，并添加注释说明来源。例如：

#define BATTERY_LOW_THRESHOLD_MV  (3200U)
if (battery_voltage_mv < BATTERY_LOW_THRESHOLD_MV) {
    /* 触发低电量告警 */
}

4.4 类型命名规则

4.4.1 核心原理：_t后缀与模块前缀

自定义类型（结构体、枚举、联合体）命名应使用typedef，并以_t结尾。类型名应包含模块前缀，避免全局命名空间冲突。例如，typedef struct _uart_dev_t uart_dev_t;。在C语言中，结构体标签（tag）通常使用小写下划线风格，而typedef后的类型名使用相同风格。

/* 推荐风格 */
typedef struct {
    uint32_t baudrate;
    uint8_t  data_bits;
    uint8_t  stop_bits;
} uart_cfg_t;

typedef struct {
    uart_cfg_t cfg;
    volatile uint32_t *base_addr;
} uart_dev_t;

4.4.2 操作流程：类型定义规范

• 所有类型定义必须使用typedef，禁止直接使用struct关键字声明变量。
• 类型名必须包含模块名或项目缩写前缀。
• 指针类型定义应明确指向，如typedef uart_dev_t *uart_dev_handle_t;。

4.4.3 案例拆解：设备句柄类型设计

在一个多传感器项目中，定义了如下类型体系：

typedef struct _sensor_temp_t sensor_temp_t;
typedef struct _sensor_humi_t sensor_humi_t;
typedef struct {
    sensor_temp_t *temp;
    sensor_humi_t *humi;
} env_sensor_t;

通过类型名即可清晰看出传感器类别，且env_sensor_t聚合了温湿度设备，便于上层调用。

4.5 文件命名规则

4.5.1 核心原理：模块化与可追溯性

源文件（.c）和头文件（.h）命名应与模块功能严格对应，采用模块名_子模块的结构。例如，uart_driver.c、uart_driver.h。头文件应使用#ifndef宏防止重复包含，宏名格式为__MODULE_NAME_H__。

/* uart_driver.h */
#ifndef __UART_DRIVER_H__
#define __UART_DRIVER_H__

/* 函数声明、类型定义等 */

#endif /* __UART_DRIVER_H__ */

4.5.2 判断方法：文件命名检查

• 文件名是否与内部主要函数或类型匹配？
• 是否避免使用main.c承载所有功能？应拆分为main.c（仅入口）、app_init.c、peripheral_config.c等。
• 驱动文件是否按外设类型分类？如led.c、key.c、lcd.c。

4.5.3 常见误区：文件命名混乱

一个常见问题是utils.c中堆放了所有杂项函数，导致文件臃肿且难以维护。应拆分为crc32.c、ring_buffer.c、math_utils.c等，每个文件职责单一。

4.6 命名风格对比：匈牙利命名法 vs 下划线风格

4.6.1 核心原理：两种风格的哲学差异

匈牙利命名法（Microsoft风格）在变量名中嵌入类型信息前缀，如dw表示DWORD、sz表示字符串、p表示指针。其优点是类型一目了然，但缺点是当类型变更时需同步修改变量名，且对嵌入式C的uint32_t等类型描述不够直观。下划线风格（Linux内核风格）强调可读性与简洁性，类型信息通过编译器保证，变量名仅表达业务含义，如adc_value、rx_buffer。

4.6.2 判断方法：如何选择

对于嵌入式C项目，强烈推荐下划线风格，原因有三：第一，嵌入式编译器对类型有严格检查，无需在命名中重复类型；第二，下划线风格与Linux内核、AUTOSAR等主流规范兼容；第三，团队协作时，下划线风格更易统一。若维护遗留代码，则遵循“随乡入俗”原则，不强行混用。

4.6.3 实战场景：混合风格带来的灾难

某项目初期由A工程师使用匈牙利命名法，后期B工程师使用下划线风格，导致代码中出现uint32_t dwCount与uint32_t count并存。代码评审时，新人无法判断dwCount与count是否同一变量，最终通过全局搜索才发现是不同变量。这一案例说明，一致性远比风格本身更重要。