87f6faee79
- Added a comprehensive guide for creating custom boards in the XiaoZhi AI project, detailing directory structure, configuration files, and initialization code. - Introduced a new document explaining the MCP protocol for IoT control, including message formats and interaction flows. - Updated existing documentation to reflect changes in tool registration and usage examples for the MCP protocol. - Enhanced README files for better clarity and consistency across languages.
91 lines
2.3 KiB
Markdown
91 lines
2.3 KiB
Markdown
# 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.
|