代码规范
本章定义电控组在 bsp-dev-c / qdu-future-modules 的统一编码规范。目标是减少风格分裂和隐性 bug。
1. 基线约束
- C++ 标准：C++17。
- 统一格式化工具：
clang-format。 - 统一编译配置由项目脚本和 CMake 管理，不在代码里硬编码工具链差异。
2. 目录与文件职责
按职责分文件，不把模块做成单大文件。
Module.hpp：类定义、接口、核心逻辑入口。ModuleDebug.inl：调试实现（仅 Debug 构建参与）。README.md：模块用途、主要函数、接入方式。
3. 命名规范
3.1 类型与文件
- 类名：
PascalCase，例如Gimbal、EventBinder。 - 文件名与主类同名，模块调试文件用
XxxDebug.inl。 - 枚举类型使用
enum class，避免命名污染。
3.2 变量与函数
- 成员变量：
snake_case_结尾下划线。 - 普通函数：
PascalCase或与现有模块保持一致，避免同模块混用。 - 常量：
kXxx或ALL_CAPS，但同一模块内部风格必须统一。
3.3 Topic 与事件名
- Topic 名使用小写下划线：
gimbal_cmd、chassis_cmd。 - 事件枚举命名可读且可区分模块语义：
SET_MODE_RELAX、SET_MODE_FOLLOW。
4. 注释规范（Doxygen）
关键接口必须用 Doxygen 注释块说明用途、参数、返回值和调用时机。
推荐模板：
/**
* @brief 更新云台控制输出
* @details 在控制线程中周期调用，完成指令解析与电机输出。
* @param dt 控制周期（秒）
* @return true 更新成功
*/
bool UpdateControl(float dt);
注释要求：
- 接口做什么，而不是“代码逐行翻译”。
- 说明调用上下文（线程/回调/周期）。
- 有副作用就写清楚（例如会发送 CAN、会发布 Topic）。
5. 函数设计规范
- 单个函数只做一类逻辑，过长函数必须拆分。
- 控制线程内流程建议拆成：
Parse -> Compute -> Output。 OnMonitor只做轻量逻辑，不做重计算或阻塞操作。
6. 并发与锁规范
- 锁粒度尽量小，持锁区只读写共享状态。
- 严禁在持锁区执行潜在阻塞外设调用（CAN/UART 阻塞写）。
- ISR/回调上下文只做快路径处理，复杂工作下放线程。
7. 错误处理规范
- 外设初始化失败必须显式处理（重试、日志、保护态）。
- 指针和硬件句柄在构造阶段完成校验。
- 明确“离线行为”：离线时输出安全值，不允许继续使用陈旧控制量。
8. Debug 代码规范
调试代码与业务代码分离，建议模式：
#ifdef DEBUG
#define XXX_DEBUG_IMPL
#include "XxxDebug.inl"
#undef XXX_DEBUG_IMPL
#endif
规则：
- Debug 接口只在 Debug 构建参与编译。
- Release 构建不引入调试命令实现。
- 调试输出要可筛选（视图化），避免刷屏影响实时性。
9. 提交前自检清单
- 已通过格式化与编译。
- 新增/修改接口已补充 Doxygen 注释。
- README 与实现一致（参数、依赖、入口）。
- Debug 与 Release 行为符合预期。
- 不引入与本次需求无关的改动。