Embedded C Coding Standard Zh

应用格式与文件组织规则

• 只使用空格缩进，每一级 4 个空格，禁止插入 TAB。
• 行宽不超过 81 列；URL、命令行、#include、#error 等确有必要时可例外。
• 使用 K&R 大括号风格：
• 函数的左大括号独占一行
• 控制语句的左大括号放在语句行末
• 右大括号通常独占一行，除非后面紧跟 else、else if 或 do { } while (0) 的尾部 while
• if、else、for、while、do、switch 一律显式使用大括号，即使只有一条语句或空循环体。
• switch 中的 case 和 default 相对 switch 缩进一级，并显式写出 break、return 或说明型 fallthrough。
• 保持一行一条语句，不要把多条动作塞进一行，也不要用晦涩写法隐藏副作用。
• 若项目使用 CMake 或 Makefile 构建，头文件搜索路径应按"底层到顶层"排序，以减少无效路径匹配并改善编译速度。推荐顺序：芯片与架构层（CMSIS、设备头）→ HAL/驱动层 → OS 与第三方中间件 → BSP/平台组件 → 应用层。
• 新建或大幅重写 .c 文件时，优先采用以下组织顺序：
• 文件头注释
• #include
• 宏与常量
• 类型定义
• 文件级 static 变量
• 内部声明
• 内部 static 函数
• 对外函数
• 新建 .c 或 .h 文件时必须使用以下文件头注释模板（替换对应字段）：

  /******************************************************************************
   * @file <filename>
   *
   * @par dependencies
   *
   * @author <Author Name>
   *
   * @brief <Brief description>
   *
   * @version V1.0 <YYYY-M-D>
   *
   * @note 1 tab == 4 spaces!
   *****************************************************************************/
  

• 所有函数声明，和函数定义需要包含注释，必须使用以下注释模板：

  /**
  * @brief
  * 
  * @param[in] : 
  * 
  * @param[out] : 
  * 
  * @return
  * 
  * */
  

• 函数内部注释，需要遵循下面意见，注释统一写在代码前一行，必须使用以下注释模板：

  /**
  * This is a comment
  **/
  

• 注释默认用英文，重点说明设计意图、边界条件、硬件约束和非显然取舍，不要机械复述代码本身。每个函数都必须要有函数内注释。

应用安全性、可维护性与可移植性规则

• 让每个函数尽量只做一件事。可行时将函数控制在 60 行非空非注释代码以内，嵌套层级不超过 4 层。
• 对任何可能失败的 API，调用后立即检查返回值，包括项目接口、HAL、OS、内存分配、I/O 等。
• 同一模块内部尽量保持一致的返回值策略，不要混用多套错误语义。
• 对所有外部输入做显式校验，包括 API 入参、文件数据、网络报文、IPC 数据、环境信息，以及跨信任边界的共享全局状态。
• 不要用 assert 校验外部输入；assert 仅用于内部不变量。
• 对动态内存、锁、句柄、队列、信号量等资源，确保所有退出路径都能正确释放；资源较多时优先使用 cleanup: 收口。
• 优先使用函数或 static inline 替代函数式宏；若必须使用宏，必须完整加括号，多语句宏必须写成 do { ... } while (0)。
• 尽量减少全局状态；如果符号只在当前文件使用，就声明为 static。对文件级或全局可变状态使用 g_ 前缀。
• 若文件级可变状态可能被多线程或中断上下文访问，必须明确同步策略，如互斥锁、原子、关中断或单线程约束。
• 指针运算优先使用 uintptr_t 或字节指针；不要通过 uint32_t 传递或截断指针。
• 长度、大小和索引优先使用 size_t；若必须缩窄到 32 位，先做显式边界检查。
• 生产代码优先走项目统一日志接口，不要随意保留 printf；同时避免打印敏感数据。
• 调试钩子、临时日志和测试代码不要混入发布路径；如必须保留，使用编译开关保护。

审查与整改时的优先级

• 先处理正确性、安全性、资源生命周期、并发和可移植性问题，再处理纯风格问题。
• 重点关注以下问题：
• 未检查返回值
• 未校验外部长度或范围
• 宏副作用与括号缺失
• 控制语句缺少大括号
• 指针截断
• size_t 缩窄
• 内存泄漏、重复释放、释放非法对象
• 本应是 static 的新增全局状态
• 除非用户明确要求，否则不要为了"看起来更整齐"而整文件重排或全量格式化。

需要更详细规则时再加载参考文档

• 如需做大规模 review、制定 CI 门禁，参考 .agents/skills/embedded-c-coding-standard-zh/references/embedded-c-rules-zh.md。
• 构建静态检查配置时，优先从参考文档中的示例派生，不要随意发明与嵌入式规范无关的新规则。