Skip to content

AudioLab Code Quality Standards

Status: ✅ Automation Complete Last Updated: 2025-10-03

📋 Overview

Comprehensive code quality automation for AudioLab using industry-standard tools:

  • clang-format - Automatic code formatting
  • clang-tidy - Static analysis and linting
  • Pre-commit hooks - Automated quality gates

Purpose: Ensure consistent, high-quality code across the entire AudioLab project.

🚀 Quick Start

1. Install Tools

Windows: 

winget install LLVM.LLVM

macOS: 

brew install llvm clang-format clang-tidy

Linux: 

sudo apt install clang-format clang-tidy

2. Install Pre-Commit Hook

# From project root
pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/install_hooks.ps1"

3. Format Your Code

# Check formatting (non-destructive)
pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/format_all.ps1" -Check

# Fix formatting
pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/format_all.ps1"

4. Run Linter

# Lint all code
pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/lint_all.ps1"

# Lint specific path
pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/lint_all.ps1" -Path "04_CORE/04_02_math_primitives"

📁 File Structure

03_10_quality_standards/
├── README.md (this file)
├── scripts/
│   ├── format_all.ps1        # Format all C++ files
│   ├── lint_all.ps1           # Run clang-tidy linter
│   └── install_hooks.ps1      # Install git hooks
├── hooks/
│   └── pre-commit             # Pre-commit hook (checks formatting)
└── 03_10_00_formatting_rules/
    ├── FORMAT_AUTOMATION.md
    └── FORMAT_EXEMPTIONS.md

Root Configuration Files: 

2 - FOUNDATION/
├── .clang-format              # Formatting rules
└── .clang-tidy                # Linting rules

🎨 Code Formatting (.clang-format)

AudioLab Style Guide

Based on: LLVM with AudioLab customizations

Key Rules: - Indentation: 4 spaces (no tabs) - Line length: 100 characters - Braces: Attach style (if (condition) {) - Pointer alignment: Left (float* ptr) - Naming: - Classes: CamelCase - Functions/variables: lower_case - Constants: UPPER_CASE

Configuration: 2 - FOUNDATION/.clang-format

Example

Before formatting: 

float     calculateGain(float input_db,float threshold){
if(input_db>threshold){return std::exp((input_db-threshold)*0.1f);
}return 1.0f;}

After formatting: 

float calculate_gain(float input_db, float threshold) {
    if (input_db > threshold) {
        return std::exp((input_db - threshold) * 0.1f);
    }
    return 1.0f;
}

Usage

Check formatting: 

.\scripts\format_all.ps1 -Check

Fix formatting: 

.\scripts\format_all.ps1

Format specific directory: 

.\scripts\format_all.ps1 -Path "2 - FOUNDATION/04_CORE"

🔍 Static Analysis (.clang-tidy)

Enabled Checks

Categories: - bugprone-* - Bug-prone code patterns - cert-* - CERT secure coding guidelines - clang-analyzer-* - Clang static analyzer - concurrency-* - Thread safety issues - cppcoreguidelines-* - C++ Core Guidelines - modernize-* - Modern C++ (C++17/20) - performance-* - Performance optimizations - portability-* - Cross-platform issues - readability-* - Code readability

Disabled (noisy): - modernize-use-trailing-return-type - readability-identifier-length - cppcoreguidelines-avoid-magic-numbers - readability-magic-numbers

Configuration: 2 - FOUNDATION/.clang-tidy

Naming Conventions

Classes/Structs:   CamelCase       (AudioProcessor)
Functions/Methods: lower_case      (process_audio)
Variables:         lower_case      (sample_rate)
Constants:         UPPER_CASE      (MAX_BUFFER_SIZE)
Members:           lower_case_     (sample_rate_)
Namespaces:        lower_case      (audiolab::core)

Usage

Lint all code: 

.\scripts\lint_all.ps1

Lint with auto-fix (use caution): 

.\scripts\lint_all.ps1 -Fix

Lint specific checks: 

.\scripts\lint_all.ps1 -Checks "performance-*,bugprone-*"

🪝 Git Hooks

Pre-Commit Hook

What it does: 1. Runs on git commit 2. Checks formatting of staged C++ files 3. Blocks commit if formatting is incorrect

Installation: 

pwsh .\scripts\install_hooks.ps1

Bypass (NOT recommended): 

git commit --no-verify

Hook Workflow

Developer commits code
         ↓
Pre-commit hook runs
         ↓
   Format check
         ↓
   Pass? ────→ Yes ─→ Commit succeeds
     ↓
    No
     ↓
Commit blocked
     ↓
Run format_all.ps1
     ↓
Re-commit

🛠️ IDE Integration

Visual Studio Code

Settings (.vscode/settings.json): 

{
    "editor.formatOnSave": true,
    "C_Cpp.clang_format_style": "file",
    "C_Cpp.codeAnalysis.clangTidy.enabled": true,
    "C_Cpp.codeAnalysis.clangTidy.path": "clang-tidy"
}

CLion

Settings: 1. Settings → Editor → Code Style → C/C++ 2. Scheme: Project 3. Automatically reads .clang-format

Clang-Tidy: 1. Settings → Editor → Inspections → C/C++ 2. Enable Clang-Tidy 3. Use .clang-tidy config

Visual Studio

Tools → Options: 1. Text Editor → C/C++ → Formatting 2. Use custom clang-format.exe: Browse to clang-format 3. Enable ClangFormat support: Yes 4. Style: file

📊 CI/CD Integration

GitHub Actions

name: Code Quality

on: [push, pull_request]

jobs:
  format-check:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install LLVM
        run: choco install llvm
      - name: Check Formatting
        run: pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/format_all.ps1" -Check

GitLab CI

format-check:
  stage: quality
  script:
    - pwsh "2 - FOUNDATION/03_INFRA/03_10_quality_standards/scripts/format_all.ps1" -Check
  only:
    - merge_requests

📝 Exemptions & Special Cases

Format Exemptions

Use // clang-format off and // clang-format on for: - DSP coefficient arrays - Lookup tables - Matrix initializations - ASCII art diagrams

Example: 

// clang-format off
constexpr float COEFFICIENTS[] = {
    1.0f,           0.5f,           0.25f,
    0.1666667f,     0.0833333f,     0.0416666f
};
// clang-format on

Documentation: FORMAT_EXEMPTIONS.md

Lint Suppressions

Suppress specific warnings: 

// NOLINTNEXTLINE(performance-unnecessary-copy-initialization)
auto copy = expensive_object;  // Intentional copy

// NOLINT(cppcoreguidelines-avoid-magic-numbers)
constexpr float PI = 3.14159f;  // Well-known constant

Documentation: SUPPRESSION_GUIDE.md

🧪 Testing Quality Automation

Verify Installation

# 1. Check tools installed
clang-format --version
clang-tidy --version

# 2. Test formatting script
pwsh .\scripts\format_all.ps1 -Check

# 3. Test linting script
pwsh .\scripts\lint_all.ps1 -Path "04_CORE/04_02_math_primitives"

# 4. Test pre-commit hook
git add .
git commit -m "test"  # Hook should run

Expected Output

Format check (passing): 

═══════════════════════════════════════════════
  AudioLab Code Formatter (clang-format)
═══════════════════════════════════════════════

✓ Using: C:\Program Files\LLVM\bin\clang-format.exe
Found 156 files

  ✓ 2 - FOUNDATION/04_CORE/04_02_math_primitives/00_fast_math/fast_exp_log.hpp
  ✓ 2 - FOUNDATION/04_CORE/04_02_math_primitives/tests/test_fast_exp_log.cpp
  ...

✅ All 156 files properly formatted!

Lint check (passing): 

═══════════════════════════════════════════════
  AudioLab Code Linter (clang-tidy)
═══════════════════════════════════════════════

✓ Using: C:\Program Files\LLVM\bin\clang-tidy.exe
Found 42 files to lint

[1/42] Linting: fast_exp_log.cpp
  ✓ Clean
[2/42] Linting: test_fast_exp_log.cpp
  ✓ Clean
...

✅ No linting issues found!

🔧 Troubleshooting

Common Issues

1. "clang-format not found"

Solution: 

# Windows
winget install LLVM.LLVM

# Verify installation
clang-format --version

2. "compile_commands.json not found"

Solution: 

# Generate with CMake
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

3. "Hook not executing"

Solution: 

# Reinstall hooks
pwsh .\scripts\install_hooks.ps1 -Force

# Verify hook exists
ls .git/hooks/pre-commit

4. "Too many warnings"

Solution: 

# Fix auto-fixable issues
pwsh .\scripts\lint_all.ps1 -Fix

# Suppress specific warnings (see SUPPRESSION_GUIDE.md)

📈 Metrics & Reporting

Quality Dashboard

# Generate quality report
pwsh .\scripts\quality_report.ps1

Tracks: - Formatting compliance: X% of files pass - Linting issues: Y warnings, Z errors - Hook adoption: XX% of commits use hooks

Pre-Release Checklist

Before major releases: - [ ] All files formatted (format_all.ps1 -Check passes) - [ ] No critical lint errors (lint_all.ps1 passes) - [ ] Pre-commit hooks installed for all developers - [ ] CI/CD quality gates passing

🎯 Goals & Roadmap

✅ Completed (Phase 1)

  • .clang-format configuration
  • .clang-tidy configuration
  • Formatting automation script
  • Linting automation script
  • Pre-commit hook
  • Hook installer
  • Documentation

🔄 In Progress (Phase 2)

  • CI/CD integration (GitHub Actions, GitLab CI)
  • Quality dashboard
  • IDE setup automation

📋 Planned (Phase 3)

  • Custom clang-tidy checks for AudioLab
  • Performance linting (cache misses, vectorization)
  • Audio-specific checks (denormal handling, NaN detection)

🤝 Contributing

Adding New Checks

  1. Edit .clang-tidy to add check
  2. Test on existing code
  3. Document in SUPPRESSION_GUIDE.md
  4. Update this README

Modifying Style

  1. Edit .clang-format
  2. Run format_all.ps1 on entire codebase
  3. Review diff carefully
  4. Create PR with justification

📄 License

AudioLab code quality standards are part of the AudioLab project. See main project LICENSE for details.

Last Updated: 2025-10-03 Maintained by: AudioLab Infrastructure Team Questions? See TROUBLESHOOTING.md