程式碼風格指南

本文件介紹小智 ESP32 專案的程式碼風格規範，專案使用 clang-format 工具來統一程式碼風格。

工具介紹

專案根目錄提供了 .clang-format 配置檔案，該配置基於 Google C++ 風格指南，並做了一些自定義調整。

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

# Ubuntu/Debian
sudo apt install clang-format

# Fedora
sudo dnf install clang-tools-extra

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

專案自有 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