AgentSkillsCN

C++ Code Formatter

在 Sanmill 项目中规范 C++ 代码的格式，确保代码风格的一致性；适用于格式化 C++ 代码，或检查代码风格合规性的场景。

SKILL.md
--- frontmatter
name: "C++ Code Formatter"
description: "Format C++ code in Sanmill project to ensure consistent code style; use when formatting C++ code or checking code style compliance."

C++ Code Formatter

Purpose

This skill helps format Sanmill's C++ code to ensure code style consistency and maintainability across the codebase.

Use Cases

  • •Format C++ code after modifications
  • •Check code style compliance
  • •Format code before committing
  • •Batch format project C++ files
  • •Validate code style in CI/CD pipelines

Quick Commands

Using Project Script (Recommended)

bash
# Format all C++ and Dart code (will auto-commit)
./format.sh

# Format without auto-commit
./format.sh s

The script formats:

  • •All .h and .cpp files in src/, include/, tests/
  • •All Dart files in the project
  • •Uses project's .clang-format configuration

Manual Formatting

bash
# Format single file
clang-format -i src/position.cpp

# Format multiple files
clang-format -i src/*.cpp src/*.h

# Check without modifying (dry-run)
clang-format --dry-run --Werror src/position.cpp

Configuration

Project Configuration Files

  • •.clang-format - C++ formatting rules (project root)
  • •CPPLINT.cfg - Code style checking rules
  • •.editorconfig - Editor-specific settings

View Current Configuration

bash
cat .clang-format

Code Style Checking

bash
# Check specific file with cpplint
cpplint --config=CPPLINT.cfg src/position.cpp

# The configuration file defines which checks to enable/disable

Git Integration

Pre-commit Workflow

bash
# 1. Make code changes
# 2. Format code
./format.sh s

# 3. Review changes
git diff

# 4. If correct, commit
git add .
git commit -m "Your commit message"

Format Only Staged Files

bash
git diff --cached --name-only --diff-filter=ACM | \
grep -E '\.(cpp|h|cc|hpp)$' | \
xargs clang-format -i

Common Issues & Solutions

1. Format Breaks Code Structure

  • •Check: Verify .clang-format configuration
  • •Check: Ensure clang-format version matches team standard
  • •Workaround: Use // clang-format off and // clang-format on for special blocks

2. Batch Formatting Creates Large Changes

  • •Solution: Format in batches and commit separately
  • •Label: Use clear commit message like "style: Format C++ code"
  • •Communicate: Notify team members to sync

3. Format Conflicts Between Developers

  • •Ensure: All use same .clang-format file
  • •Ensure: All use same clang-format version
  • •Establish: Team formatting conventions

Best Practices

  1. •Format frequently: Format after each significant change
  2. •Format before commits: Always format before committing
  3. •Review formatting changes: Don't blindly commit formatting
  4. •Use project script: Prefer ./format.sh over manual commands
  5. •Separate formatting commits: Keep formatting separate from logic changes
  6. •Don't hand-edit formatting: Let tools do the work

Tools Required

clang-format

bash
# Check if installed
clang-format --version

# Install on Ubuntu/Debian
sudo apt-get install clang-format

# Install on macOS
brew install clang-format

cpplint (Optional)

For additional style checking beyond formatting.

Output Format

Formatting operations should report:

  • •✓ Files formatted successfully
  • •⚠ Files with style violations
  • •✗ Files that failed to format
  • •📊 Total files processed
  • •💡 Style improvement recommendations

Reference Resources

  • •Configuration: .clang-format, CPPLINT.cfg, .editorconfig (project root)
  • •Format script: format.sh (project root)
  • •clang-format docs: https://clang.llvm.org/docs/ClangFormat.html
  • •C++ source locations: src/, include/, tests/