embedded-c-coding-standard-zh-v2

name	embedded-c-coding-standard-zh-v2
description	按嵌入式 C 语言编码规范编写、重构、审查和整理固件代码。用于 STM32、RTOS、BSP、HAL、驱动、服务层、中间件等场景下的 `.c` 文件与相关 `.h` 文件工作，特别适用于用户请求提到C语言编码规范、命名统一、注释补齐、大括号风格、返回值检查、内存安全、32/64位可移植性、静态检查、Git 变更增量审查或代码风格整改时。

嵌入式 C 语言编码规范 V2

按嵌入式规范处理项目自有嵌入式 C 代码，并尽量控制改动范围，避免产生无意义的大 diff。

V2 默认工作模式

• 当任务是 review、审查、整改、提交前检查、看本次改动有没有问题 这类增量检查时，优先使用 Git 变更范围，而不是全工程扫描。
• 增量审查默认只锁定本次变更涉及的自研 .c/.h 文件，再结合函数级上下文、同模块头文件和直接关联定义做审查。
• 不要机械地只看 diff 行；要把 diff 当入口，再补读当前函数、必要的结构体、宏定义、枚举、资源释放路径和直接相关接口。
• 只有在用户明确要求全量扫描、建立初始基线、做大规模规范治理、批量重构或 CI 规则收敛时，才转为目录级或全工程审查。
• 若当前目录不是 Git 仓库，或仓库状态不足以确定基线，则退化为用户指定文件范围、目录范围或当前任务涉及文件的局部审查。

先判断审查范围

• 如果用户没有明确要求全量扫描，且当前工作区是 Git 仓库，优先通过 Git 确定增量范围。
• 优先审查以下几类范围：
• 工作区未提交变更
• 暂存区变更
• 当前分支相对基线分支的变更
• 只将变更集中的自研 .c、.h 文件纳入默认审查范围；生成代码、第三方代码和构建产物默认排除。
• 若用户说“只看这次提交”“只看这次改动”“只审变更文件”，默认就是增量审查，不再主动扩展到全仓。
• 若变更文件很少，但影响到公共头文件、宏定义、共享结构体或资源生命周期，可按需补读直接相关文件；不要无边界扩散。

先判断代码归属

• 先判断目标文件属于项目自研代码、自动生成代码，还是第三方代码。

• 默认将 Drivers/、03_Os/、外部中间件，以及 Core/ 下大多数 STM32Cube 生成文件视为自动生成或上游代码。
• 若目标属于第三方或生成代码，除非用户明确要求统一风格，否则只修改必要逻辑，尽量保留原有布局和上游风格。
• 若规范与上游风格冲突，优先保持局部一致性，并在最终回复里说明这是例外处理。

先消解文档里的歧义

• 把原始规范文档视为“以 .c 实现文件为中心”的规范：所有 MUST 规则默认对 .c 生效；只有在确实修改接口时，才把命名、注释、宏和接口相关规则同步应用到 .h。
• 当原文摘要表、正文和示例互相冲突时，优先级按以下顺序处理：
• 安全性和正确性规则
• 正文详细说明与具体示例
• 仓库内稳定的既有约定
• 摘要表中的简写结论
• 在项目自有代码中新建标识符时，默认采用以下归一命名规则：
• 文件名与函数名：snake_case
• 局部变量与参数：lowerCamelCase
• 文件级或全局可变状态：g_ + lowerCamelCase
• 宏、枚举值、标签：UPPER_SNAKE_CASE
• typedef 后的抽象类型名：PascalCase
• 不要为了追求风格统一去大面积重命名稳定公共 API、生成代码符号、厂商接口或已有调用链，除非用户明确要求。

应用格式与文件组织规则

• 只使用空格缩进，每一级 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 的新增全局状态
• 除非用户明确要求，否则不要为了“看起来更整齐”而整文件重排或全量格式化。

V2 Git 增量审查指引

• 在 Git 仓库中，优先使用以下思路确定审查范围：
• 工作区未提交：git status --short + git diff --name-only
• 暂存区：git diff --cached --name-only
• 分支差异：git diff --name-only <base>...HEAD
• 变更过滤时优先保留项目自研模块（按项目实际目录结构识别，如应用层、服务层、平台层、BSP、工具库等自研目录）。
• 默认排除：
• Drivers/
• 03_Os/
• 外部中间件
• Core/ 下大多数生成代码
• 构建产物、日志和临时文件
• 审查输出要聚焦本次变更引入的问题；历史遗留问题可简短提示，但不要让它们淹没本次改动的 findings。
• 若用户明确要求“顺带给出历史问题”或“建立基线”，再额外列出非本次改动问题。
• 若 Git 不可用，明确说明已退化为局部范围审查，并说明当前使用的范围选择依据。

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

• 做大规模 review、制定 CI 门禁、补 .clang-format、.clang-tidy、cppcheck 规则时，再读取 references/embedded-c-rules-zh.md。
• 需要把 Git 增量审查流程讲清楚、给出范围选择示例或说明为何不做全仓扫描时，再读取 references/git-incremental-review-zh.md。
• 构建静态检查配置时，优先从参考文档中的示例派生，不要随意发明与嵌入式规范无关的新规则。