C 语言命名约定 (自用参考)

最重要的一致性规则是命名管理。命名的风格能让我们在不需要去查找类型声明的条件下快速地了解某个名字代表的含义：类型、变量、函数、常量、宏等等。我们大脑中的模式匹配引擎非常依赖这些命名规则。

0. 历史上的三大命名法

在现代编程中，以下三种命名法最为经典，各有优劣：

1. 蛇形命名法 (Snake Case)
   • 特征：单词全部小写，用下划线 _ 连接。
   • 示例：max_buffer_size, user_name
   • 应用：Linux 内核、Python 标准库、C 标准库。
2. 驼峰命名法 (Camel Case)
   • 小驼峰 (lowerCamelCase)：首字母小写，后续单词首字母大写。示例：maxBufferSize。
   • 大驼峰 (PascalCase)：每个单词首字母均大写。示例：MaxBufferSize。
   • 应用：Java, C#, JavaScript, C++ 库（如 Qt）。
3. 匈牙利命名法 (Hungarian Notation)
   • 特征：在变量名前面加上表示其类型的小写字母。
   • 示例：iCount (int), szName (string zero-terminated), pData (pointer)。
   • 应用：早期的 Windows 开发（Win32 API）。

---

在嵌入式开发中，我们综合了上述优点，建议采用改进型匈牙利命名法，结合模块化前缀。

1. 通用命名规则

• 见名知意：严禁使用 a, b, c 等无意义变量（循环变量 i, j, k 除外）。宁可名字长一点，也不要让人猜。例如使用 BufferIndex 而不是 Idx。
• 英文语义化：严禁使用拼音或拼音缩写。统一使用“动词+名词”或“名词+形容词”的英文组合。
• 避免魔术数字：代码中不允许出现未定义的常数，必须用宏或枚举代替。
• 长度适中：名称通常在 4-20 个字符之间。
• 缩写规范：行业通用缩写（如 ADC, DMA, UART, CRC）必须全大写或全小写，不要混用（如使用 Adc 或 Dma 会破坏连贯性）。

2. 文件命名

采用 小写字母 + 下划线 (lower_snake_case)，体现模块化。

• 规则：模块名_功能名.c/h
• 示例：
  • hal_uart.c （硬件抽象层串口驱动）
  • app_motor_control.c （应用层电机控制）
  • sys_config.h （系统配置文件）

3. 变量命名

采用 “组合前缀（作用域+类型/修饰符） + 下划线 + 语义名” 的方式。语义名也可以使用驼峰式命名，根据项目灵活调整。这种方式移除了作用域后的下划线，使变量名更加紧凑。

3.1 前缀定义表

分类	前缀	代表类型 / 含义	备注
基础类型	u8	uint8_t	8位无符号整型
	s8	int8_t	8位有符号整型
	u16	uint16_t	16位无符号整型
	u32	uint32_t	32位无符号整型
	b	bool / boolean	布尔值
	f	float	单精度浮点数
复合类型	st	struct	结构体变量
修饰前缀	p	pointer	指针（如 pu8）
	a	array	数组（如 au8）
作用域	g	global	全局变量前缀
	s	static	静态变量前缀（局部或全局静态）

作用域s不常用，在实际项目中可选使用。

3.2 组合规则与示例

1. 全局变量：g + 类型 + _ + 语义名。示例：gu8_BatteryLevel, gst_SystemConfig
2. 静态变量：s + 类型 + _ + 语义名。示例：su16_SampleCount, sst_MotorState
3. 普通局部变量：类型 + _ + 语义名。示例：u32_SystemTicks, st_DataPacket
4. 指针/数组组合：修饰符置于类型前。
   • pu8_DataPtr （局部指针，指向 uint8）
   • gpst_DeviceHandle （全局结构体指针）
   • sau16_AdcRaw （静态 uint16 数组）

• 综合示例：
  • uint8_t gu8_BatteryLevel; （全局变量）
  • static uint16_t sau16_AdcRaw[10]; （静态数组）
  • char *pstr_ErrInfo; （局部指针）
  • bool b_IsConnected; （布尔变量）
  • MyStruct_t st_DataPacket; （局部结构体变量）

4. 函数命名

采用 模块名 + 动作名词 的形式，单词首字母大写。

• 规则：模块名_动作名词()
• 示例：
  • Uart_Init()
  • Motor_SetSpeed()
  • Led_Toggle()

5. 枚举命名

• 枚举类型名：大驼峰命名 (PascalCase)，通常以 _t 结尾。
• 枚举成员：全大写，带上类型缩写前缀。
• 示例：

  typedef enum {
      SYS_STATUS_IDLE = 0,
      SYS_STATUS_RUNNING,
      SYS_STATUS_ERROR
  } SystemStatus_t;

6. 宏命名

• 规则：全大写字母，单词间用下划线分隔。
• 示例：
  • #define MAX_BUFFER_SIZE 256
  • #define GET_MIN(a, b) ((a) < (b) ? (a) : (b))