This guide provides step-by-step instructions for setting up consistent formatting, rules checking, and documentation for C/C++ code using clang-format, clang-tidy, and Doxygen in VS Code. Follow this guide to ensure uniformity across the team.

1. Prerequisites

Before starting, ensure you have the following tools installed:

  1. VS Code (latest version)
  2. Extensions for VS Code:
  3. Command-line tools:
    • clang-format
    • clang-tidy
    • doxygen
    • Python (for pre-commit hooks)

2. Auto-Formatting Using clang-format

clang-format is used for consistent code formatting.

Install clang-format

Install it via your package manager:

  • Linux: sudo apt install clang-format
  • macOS: brew install clang-format
  • Windows: Install via LLVM Windows Installer.

Create a .clang-format Configuration File

In your project root directory, create a file named .clang-format with the following configuration:

BasedOnStyle: LLVM
IndentWidth: 4
TabWidth: 4
UseTab: Never
BreakBeforeBraces: Allman
AllowShortFunctionsOnASingleLine: Empty
ColumnLimit: 80

Integrate clang-format with VS Code

  1. Open VS Code settings (Ctrl+Shift+P → “Preferences: Open Settings (JSON)”).
  2. Add the following configuration:
"[c]": {
  "editor.defaultFormatter": "ms-vscode.cpptools",
  "editor.formatOnSave": true
},
"[cpp]": {
  "editor.defaultFormatter": "ms-vscode.cpptools",
  "editor.formatOnSave": true
}

Format Code

To format code manually:

  • Select Ctrl+Shift+P → Format Document.

3. Rules Checking Using clang-tidy

clang-tidy enforces coding standards and checks for errors.

Install clang-tidy

  • Linux: sudo apt install clang-tidy
  • macOS: brew install llvm
  • Windows: Install via LLVM Windows Installer.

Create a .clang-tidy Configuration File

In your project root directory, create a file named .clang-tidy with the following configuration:

Checks: >
  - readability-identifier-naming,
  - readability-function-size,
  - modernize-use-nullptr,
  - misc-misplaced-widening-cast  

CheckOptions:
  - { key: readability-identifier-naming.VariableCase, value: lower_case }
  - { key: readability-identifier-naming.StructCase, value: CamelCase }
  - { key: readability-identifier-naming.EnumCase, value: UPPER_CASE }
  - { key: readability-identifier-naming.FunctionCase, value: camelBack }

Integrate clang-tidy with VS Code

  1. Open VS Code settings (Ctrl+Shift+P → “Preferences: Open Settings (JSON)”).
  2. Add the following configuration:
"C_Cpp.codeAnalysis.clangTidy.enabled": true,
"C_Cpp.codeAnalysis.clangTidy.path": "/path/to/clang-tidy", // If it is not automatically detected
"C_Cpp.codeAnalysis.clangTidy.checks": "readability-identifier-naming"

Run clang-tidy

To analyze your code:

clang-tidy file.c -- -I/path/to/include

4. Documentation Using Doxygen

Doxygen generates documentation for your code and enforces comments for functions, structs, and enums.

Install Doxygen

  • Linux: sudo apt install doxygen
  • macOS: brew install doxygen
  • Windows: Download from Doxygen.

Configure Doxygen

Generate a default configuration file:

doxygen -g

Edit the Doxyfile as needed for your project.

Generate Doxygen Comments

  1. Install the Doxygen Documentation Generator extension in VS Code.
  2. Place the cursor on a function or struct and run: Ctrl+Shift+P → Generate Doxygen Comment.

5. Automate Formatting and Linting with Pre-Commit Hooks

Set up pre-commit hooks to enforce formatting and linting before commits.

Install Pre-Commit

pip install pre-commit

Create a .pre-commit-config.yaml File

In your project root directory, create the following configuration file:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v15.0.0  # Use the desired clang-format version
    hooks:
      - id: clang-format
        args: [--style=file]
  - repo: https://github.com/pocc/pre-commit-clang-tidy
    rev: v1.2
    hooks:
      - id: clang-tidy
        args: [--config-file=.clang-tidy]

Install the Hooks

Run the following command to install the pre-commit hooks:

pre-commit install

Now, clang-format and clang-tidy will automatically check and format your code before commits.

6. CI/CD Integration (Optional)

Add clang-format and clang-tidy to your CI/CD pipeline for continuous enforcement of standards.

Example GitHub Actions Workflow

name: C/C++ Lint and Format
on: [push, pull_request]
jobs:
  lint-and-format:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Run clang-format
        run: clang-format --dry-run --Werror src/**/*.c

      - name: Run clang-tidy
        run: clang-tidy src/**/*.c -- -Iinclude

7. Sharing the Setup with Your Team

  1. Commit Configuration Files:
    • Add .clang-format, .clang-tidy, Doxyfile, and .pre-commit-config.yaml to version control.
  2. Document Workflow:
    • Share this guide with all team members.
  3. Provide Setup Script:
    • Create a setup.sh script for easy setup:
#!/bin/bash
sudo apt install clang-format clang-tidy doxygen
pip install pre-commit
pre-commit install