embedded-c-coding

# 嵌入式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. **编码风格** - 匹配同目录下文件的结构和格式约定 ## 驱动开发检查清单 编写新驱动时： 1. 内部工作线程 + 消息队列实现非阻塞操作 2. 周期性轮询留在驱动内部，不对外暴露 3. 错误状态变化通过回调通知应用层 4. 不暴露与业务无关的接口 5. 完成后文档化应用层使用须知，包括：初始化顺序、 线程安全保证、回调上下文和清理要求 ## SOLID速查 设计或修改模块结构时： - **SRP（单一职责）**：一个模块 = 一个职责 = 一个变更理由 - **OCP（开闭原则）**：通过函数指针表扩展，而非修改代码 - **LSP（里氏替换）**：所有接口实现遵守相同的契约 - **ISP（接口隔离）**：使用者只依赖其使用的接口 - **DIP（依赖倒置）**：高层依赖抽象，而非底层 ## Clean Code速查 编写任何函数时： - **一件事**：函数只做一件事 - **同层级**：所有操作处于相同的抽象层级 - **无副作用**：查询函数不修改状态 - **DRY**：如果在复制粘贴，提取共享函数 - **表驱动**：用查找表替代冗长的if-else/switch - **防御性**：断言契约、校验输入、传播错误 ## 参考文档 按领域组织的详细规格： | 参考文档 | 何时阅读 | |---------|---------| | [architecture.md](references/architecture.md) | 模块设计、OOP模式、接口、回调 | | [design-patterns.md](references/design-patterns.md) | SOLID原则、C语言GoF模式（状态机、观察者、策略、工厂） | | [clean-code.md](references/clean-code.md) | Clean Code + 华为规范：命名、防御性编程、错误处理、const/static | | [memory-safety.md](references/memory-safety.md) | 堆分配、线程安全、共享资源、防御性编码 | | [hardware-interaction.md](references/hardware-interaction.md) | HAL、寄存器、外设、事件驱动框架 / RTC | | [code-style.md](references/code-style.md) | 格式、命名、注释、宏、头文件保护 | | [safety-checklist.md](references/safety-checklist.md) | **每次编辑后强制执行** - 12阶段安全审查 |