代码风格指南

本文档介绍小智 ESP32 项目的代码风格规范，项目使用 clang-format 工具来统一代码风格。

工具介绍

项目根目录提供了 .clang-format 配置文件，该配置基于 Google C++ 风格指南，并做了一些自定义调整。

主要格式规则

安装 clang-format

Windows

winget install LLVM
# 或者使用 Chocolatey
choco install llvm

Linux

# Ubuntu/Debian
sudo apt install clang-format

# Fedora
sudo dnf install clang-tools-extra

macOS

brew install clang-format

使用方法

格式化单个文件

clang-format -i path/to/your/file.cpp

格式化整个项目

# 在项目根目录下执行
find main -iname *.h -o -iname *.cc | xargs clang-format -i

提交前检查格式

# 检查文件格式是否符合规范（不修改文件）
clang-format --dry-run -Werror path/to/your/file.cpp

IDE 集成

Visual Studio Code

1. 安装 C/C++ 扩展
2. 在设置中启用 C_Cpp.formatting 为 clang-format
3. 可设置保存时自动格式化：editor.formatOnSave: true

CLion

1. 设置 > Editor > Code Style > C/C++
2. 将 Formatter 设置为 clang-format
3. 选择使用项目中的 .clang-format 配置文件

C++ 运行时与错误处理

• 项目自有 C++ 代码以 GNU C++23 为基线，main/ 中不得依赖更高版本的语言特性。
• 关闭 C++ 异常和 RTTI，不使用 throw、try/catch、dynamic_cast 或 typeid。
• 所有权资源使用 RAII，包括需要显式释放的 ESP-IDF 句柄和 C API 资源。除非接口明确说明，裸指针均视为非拥有指针。
• 需要携带错误值的可恢复失败使用 std::expected<T, E>。高频路径优先使用小型枚举或 esp_err_t，只在协议或 UI 边界转换为字符串。
• 解引用 expected 前必须检查状态。异常关闭时，不得对未检查的结果调用 value()，否则错误访问会直接终止固件。
• 程序员不变量被破坏时使用断言或显式终止，不把它伪装成可恢复运行时错误。
• 实时音频路径使用有界队列并避免重复分配。上限已知时优先固定容量存储；只有性能分析证明存在分配抖动或堆碎片后才引入对象池。

特殊处理

禁用格式化

如果某段代码不希望被格式化，可以使用注释包围：

// clang-format off
// 你的代码
// clang-format on

注意事项

1. 提交代码前：请确保代码已经过格式化
2. 不要手动调整：已格式化的代码对齐
3. 配置文件位置：确保使用项目根目录下的 .clang-format 配置
4. 文件编码：验证文件编码为 UTF-8

常见问题

格式化失败

• 检查 clang-format 版本是否过低
• 确认文件编码为 UTF-8
• 验证 .clang-format 文件语法是否正确

与期望格式不符

• 检查是否使用了项目根目录下的 .clang-format 配置
• 确认没有其他位置的 .clang-format 文件被优先使用

相关链接

• LLVM Clang-Format 文档
• Google C++ 风格指南