ContextQMD
Back to Xiaozhi Esp32

Code Style Guide

docs/code_style.md

2.2.62.3 KB
Original Source

Code Style Guide

Formatting Tool

This project uses clang-format to keep the code style consistent. The .clang-format file in the project root is based on the Google C++ style guide with a few project-specific tweaks.

Installing clang-format

Make sure clang-format is available before you use it:

  • Windows:

    powershell
    winget install LLVM
# or with Chocolatey
choco install llvm

  • Linux:

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

  • macOS:

    bash
    brew install clang-format

Usage

  1. Format a single file:

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

  2. Format the entire project:

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

  3. Check formatting without modifying files (useful in CI / pre-commit):

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

IDE Integration

  • Visual Studio Code:

    1. Install the C/C++ extension.
    2. Set C_Cpp.formatting to clangFormat in settings.
    3. Optionally enable editor.formatOnSave.

  • CLion:

    1. Open Editor > Code Style > C/C++ in the settings.
    2. Set Formatter to clang-format.
    3. Choose "use the .clang-format file in the project".

Main Rules

  • Indent with 4 spaces.
  • Line width capped at 100 characters.
  • Attach-style braces ({ on the same line as the control statement).
  • Pointers and references bind to the type (left alignment).
  • Includes are sorted automatically.
  • Access specifiers are indented by -4 spaces.

Notes

  1. Make sure the code has been formatted before committing.
  2. Do not fix up alignment by hand after running clang-format.
  3. To exclude a block from formatting, wrap it with:
    cpp
    // clang-format off
your code
// clang-format on

FAQ

  1. Formatting fails:

    • Check whether clang-format is too old.
    • Make sure the file is UTF-8 encoded.
    • Validate the syntax of your .clang-format file.

  2. Output differs from what you expected:

    • Verify that the .clang-format in the project root is actually picked up.
    • Make sure no other .clang-format higher in the tree is winning.

Questions and suggestions are welcome - please open an issue or a pull request.