# 嵌入式C编码规范（安全关键嵌入式系统）

这是安全关键嵌入式系统代码。缺陷可能导致系统故障甚至安全事故。
每一行代码都必须以极其谨慎的态度编写和审查。

## 核心原则

1. **安全第一** - 这是安全关键嵌入式系统软件，对每一次修改
   都要像生命攸关一样对待
2. **C语言中的SOLID** - 即使在C语言中也要应用SOLID原则；
   使用函数指针接口、不透明类型和依赖注入
3. **Clean Code** - 函数只做一件事、命名揭示意图、不重复、
   无副作用、一致的抽象层级
4. **C语言中的OOP** - 即使在C语言中也要使用面向对象设计模式；
   仅通过统一的外部接口访问设备
5. **零容忍阻塞** - 如果应用层使用事件驱动框架 / RTC（运行至完成）
   执行模型，整个调用链必须是非阻塞的
6. **验证到底层** - 检查硬件交互到寄存器级别；
   永远不要假设API是非阻塞的
7. **防御性编程** - 断言内部契约、校验外部输入、传播错误、
   绝不静默吞掉失败

## 决策树：应该阅读哪个参考文档

在编写或修改代码之前，判断哪些参考文档适用：

```
编写/修改代码？
├── 设计模块结构、接口、回调？
│   ├── 阅读 references/architecture.md
│   └── 阅读 references/design-patterns.md
│
├── 编写函数、命名、错误处理？
│   └── 阅读 references/clean-code.md
│
├── 使用堆内存、线程、共享资源？
│   └── 阅读 references/memory-safety.md
│
├── 与硬件、外设、HAL交互？
│   └── 阅读 references/hardware-interaction.md
│
├── 任何代码修改？
│   ├── 阅读 references/code-style.md
│   └── 阅读 references/safety-checklist.md（强制）
│
└── 编辑完成？
    └── 阅读 references/safety-checklist.md
        并执行每一个检查项（阶段1-12）
```

**如有疑问，阅读所有参考文档。** 对于安全关键代码，
过度检查总好过检查不足。

## 强制的编辑后协议

每次代码修改后，无论修改多小，都必须执行
`references/safety-checklist.md` 中的完整安全审查。这不是可选的。
一行代码的改动就可能引入内存泄漏、竞态条件或栈溢出。
每次后续修复后也要重新执行检查清单——修复一个问题可能引入另一个。

## 速查表：硬性规则

以下是不可商量的约束：

| 规则 | 限制 |
|------|------|
| 最大函数长度 | 80行 |
| 最大嵌套深度 | 4层 |
| 最大行宽 | 80列 |
| 最大函数参数数 | 5个（超过则组合成结构体） |
| 线程中大型局部变量 | 评估栈使用，紧张时用堆 |
| 魔法数字 | 禁止，使用宏 |
| 死代码/未使用代码 | 必须删除 |
| 非公共符号 | 必须声明为 `static` |
| 未修改的指针 | 必须使用 `const` |
| 头文件 | 必须有头文件保护宏 |
| 注释语言 | 推荐英文，或与项目一致 |
| 注释中的作者 | 兆鸣嵌入式 |

## 上下文感知编码

在编写任何代码之前，先检查周围的代码库：

1. **信号/插槽用法** - 查看同目录下的兄弟文件如何使用信号、
   回调和事件机制；遵循相同的模式
2. **头文件包含路径** - 搜索项目中其他文件如何包含同一头文件；
   使用相同的路径格式
3. **堆内存API** - 嵌入式平台可能使用非标准的malloc/free；
   检查其他文件如何分配和释放内存
4. **设备打开/关闭** - 不要直接访问设备指针；找到其他模块
   如何打开/关闭同一设备并遵循该模式
5. **编码风格** - 匹配同目录下文件的结构和格式约定

## 驱动开发检查清单

编写新驱动时：

…