小智AIチャットボット文書センター | 小智AI.Dev
開発説明
コードスタイルガイド

コードスタイルガイド

フォーマットツール

このプロジェクトでは、コードスタイルを統一するために clang-format を使います。プロジェクトのルートにある .clang-format ファイルは、Google C++ スタイルガイドをベースに、プロジェクト固有の調整を少し加えたものです。

clang-format のインストール

使う前に、clang-format が利用できることを確認してください。

  • Windows：

    winget install LLVM
# or with Chocolatey
choco install llvm

  • Linux：

    sudo apt install clang-format              # Ubuntu/Debian
sudo dnf install clang-tools-extra         # Fedora

  • macOS：

    brew install clang-format

使い方

  1. 単一のファイルを整形する：

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

  2. プロジェクト全体を整形する：

    # Run from the project root
find main -iname '*.h' -o -iname '*.cc' | xargs clang-format -i

  3. ファイルを変更せずに整形をチェックする（CI や pre-commit で便利）：

    clang-format --dry-run -Werror path/to/your/file.cpp

IDE との連携

  • Visual Studio Code：

    1. C/C++ 拡張機能をインストールします。
    2. 設定で C_Cpp.formatting を clangFormat にします。
    3. 必要に応じて editor.formatOnSave を有効にします。

  • CLion：

    1. 設定の Editor > Code Style > C/C++ を開きます。
    2. Formatter を clang-format にします。
    3. 「use the .clang-format file in the project」を選びます。

主なルール

  • インデントは 4 スペースです。
  • 行幅は最大 100 文字です。
  • 波括弧はアタッチスタイルです（{ は制御文と同じ行に置きます）。
  • ポインタと参照は型の側に寄せます（左寄せ）。
  • include は自動的に並べ替えられます。
  • アクセス指定子は -4 スペースでインデントされます。

C++ ランタイムとエラー処理

  • プロジェクトが所有する C++ コードは GNU C++23 を対象とします。main/ で、より新しい言語機能を前提にしてはいけません。
  • C++ の例外と RTTI は無効です。throw、try/catch、dynamic_cast、typeid は使わないでください。
  • 所有するリソースには、ESP-IDF のハンドルや、明示的な解放関数を持つ C API も含めて、RAII を使います。インターフェースに別の記載がない限り、生ポインタは所有権を持ちません。
  • エラー値が必要な回復可能な失敗には、std::expected<T, E> を返します。ホットパスでは、小さな enum か esp_err_t を優先し、エラーを文字列に変換するのはプロトコルや UI の境界にします。
  • expected は、参照を外す前に必ず確認します。未確認の結果に value() を呼んではいけません。例外が無効だと、不正なアクセスはファームウェアを終了させます。
  • プログラマーが守るべき不変条件の違反は、アサーションか明示的な abort で致命的として扱います。回復可能な実行時エラーとして扱ってはいけません。
  • リアルタイムの音声経路では、容量制限付きのキューを使い、繰り返しのメモリ確保を避けます。最大値が分かっているなら固定容量の領域を使い、プールを追加するのは、プロファイリングでメモリの確保と解放の繰り返しや断片化が確認できてからにします。

注意事項

  1. コミットする前に、コードが整形済みであることを確認してください。
  2. clang-format を実行したあとに、手作業で桁揃えを直さないでください。
  3. ブロックを整形の対象から外すには、次のように囲みます。
    // clang-format off
your code
// clang-format on

よくある質問

  1. 整形に失敗する：

    • clang-format が古すぎないか確認します。
    • ファイルが UTF-8 でエンコードされていることを確認します。
    • .clang-format ファイルの構文を検証します。

  2. 出力が期待と違う：

    • プロジェクトのルートの .clang-format が実際に読み込まれているか確認します。
    • ツリーの上位にある別の .clang-format が優先されていないか確認します。

質問や提案は歓迎します。Issue か Pull Request でお寄せください。

出典：78/xiaozhi-esp32 の docs/code_style.md

BluFi 設定ガイドエコシステムプロジェクト：サーバー、クライアント、移植