zhaochengbo/zhaoming-embedded/ai-coding-skill

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

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

核心原则

1. 安全第一 - 这是安全关键嵌入式系统软件，对每一次修改

都要像生命攸关一样对待

1. C语言中的SOLID - 即使在C语言中也要应用SOLID原则；

使用函数指针接口、不透明类型和依赖注入

1. Clean Code - 函数只做一件事、命名揭示意图、不重复、

无副作用、一致的抽象层级

1. C语言中的OOP - 即使在C语言中也要使用面向对象设计模式；

仅通过统一的外部接口访问设备

1. 零容忍阻塞 - 如果应用层使用事件驱动框架 / RTC（运行至完成）

执行模型，整个调用链必须是非阻塞的

1. 验证到底层 - 检查硬件交互到寄存器级别；

永远不要假设API是非阻塞的

1. 防御性编程 - 断言内部契约、校验外部输入、传播错误、

绝不静默吞掉失败

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

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

编写/修改代码？
├── 设计模块结构、接口、回调？
│   ├── 阅读 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 中的完整安全审查。这不是可选的。 一行代码的改动就可能引入内存泄漏、竞态条件或栈溢出。 每次后续修复后也要重新执行检查清单——修复一个问题可能引入另一个。

速查表：硬性规则

以下是不可商量的约束：

上下文感知编码

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

1. 信号/插槽用法 - 查看同目录下的兄弟文件如何使用信号、

回调和事件机制；遵循相同的模式

1. 头文件包含路径 - 搜索项目中其他文件如何包含同一头文件；

使用相同的路径格式

1. 堆内存API - 嵌入式平台可能使用非标准的malloc/free；

检查其他文件如何分配和释放内存

1. 设备打开/关闭 - 不要直接访问设备指针；找到其他模块

如何打开/关闭同一设备并遵循该模式

1. 编码风格 - 匹配同目录下文件的结构和格式约定

驱动开发检查清单

编写新驱动时：

1. 内部工作线程 + 消息队列实现非阻塞操作
2. 周期性轮询留在驱动内部，不对外暴露
3. 错误状态变化通过回调通知应用层
4. 不暴露与业务无关的接口
5. 完成后文档化应用层使用须知，包括：初始化顺序、

线程安全保证、回调上下文和清理要求

SOLID速查

设计或修改模块结构时：

• SRP（单一职责）：一个模块 = 一个职责 = 一个变更理由
• OCP（开闭原则）：通过函数指针表扩展，而非修改代码
• LSP（里氏替换）：所有接口实现遵守相同的契约
• ISP（接口隔离）：使用者只依赖其使用的接口
• DIP（依赖倒置）：高层依赖抽象，而非底层

Clean Code速查

编写任何函数时：

• 一件事：函数只做一件事
• 同层级：所有操作处于相同的抽象层级
• 无副作用：查询函数不修改状态
• DRY：如果在复制粘贴，提取共享函数
• 表驱动：用查找表替代冗长的if-else/switch
• 防御性：断言契约、校验输入、传播错误

参考文档

按领域组织的详细规格：