clang-format 設定

clang-format 設定 は何をしますか？

clang-format コードフォーマットツールを、すぐに使えるテンプレート、統合スクリプト、包括的なリファレンスドキュメントを用いて設定します。

目的

このスキルは、clang-format 設定タスクの手順ワークフローを提供します。

• 実績のあるテンプレートから新しい .clang-format ファイルを作成する
• 既存のコードスタイルを分析し、一致する設定を生成する
• バンドルされたスクリプトでエディタと Git の統合をセットアップする
• リファレンスドキュメントを使用してフォーマット動作のトラブルシューティングを行う

トリガータイプによるワークフロー分岐

呼び出されたら、どのトリガーが発火したかに基づいて適切なワークフローにルーティングします。

トリガー 1: clang-format への明示的な言及 → ユーザーが特定のオプションについて質問した場合: 関連カテゴリについて references/01-09.md を参照 → ユーザーが完全なリファレンスを必要とする場合: references/complete/clang-format-style-options.md に直接案内 → ユーザーが CLI の使用法について質問した場合: references/cli-usage.md を参照

トリガー 2: コードスタイル分析のリクエスト → 以下の「既存のコードスタイルの分析」ワークフローに従う → コードサンプルを体系的に調査（ブレース→インデント→スペーシング→改行→アライメント） → パターンを assets/configs/ 内の最も近いテンプレートにマッピング → 初期設定の仮説を一時設定ファイル "/tmp/<リポジトリ名>/hypothesis_<番号>.clang-format" として生成 → 影響を検証: 代表的なサンプル 3～5 個に対して clang-format --style="/tmp/<リポジトリ名>/hypothesis_<番号>.clang-format" file.cpp | diff - file.cpp を実行 → 重み付けスコアリングで影響を測定: • 指標 1: 行数の変化（追加/削除された行）- 重み 10 • 指標 2: 行内の空白の変化（既存行内のスペーシング）- 重み 1 • 影響スコア = (行数変化 × 10) + (空白変化 × 1) • スコアが低いほど、リベースコンフリクト、将来の git-diff 分析、マージリクエストの変更レビューへの影響が少なく、設定として優れている → 反復: 最も影響の大きい設定をターゲットにオプションを調整し、再テスト、スコアを比較 → 一貫したスタイルを維持しながら達成可能な最小スコアに達するまで繰り返す → ユーザーに報告: 勝者設定を以下と共に提示: • 最終影響スコアと内訳（行変更 vs 空白変更） • テストしたすべての仮説とそのスコアを比較した表 • 何が変わるかを示す diff スニペットの例と、ユーザーが自分で任意のファイルに対してテストするためのコマンド • 選択した設定の根拠 → 設定を確定する前にユーザーの承認を待つ → 承認後: 最終設定ファイルを提供

トリガー 3: 設定ファイルの操作 → 新規作成の場合: 以下の「テンプレートから新しい設定を作成」ワークフローに従う → 既存設定の修正の場合: 現在の設定を読み込み、必要な変更を特定し、関連カテゴリガイドを参照 → コードから生成する場合: トリガー 2 のワークフロー（コードスタイル分析）を使用

トリガー 4: フォーマット動作の調査 → 以下の「フォーマット問題のトラブルシューティング」ワークフローに従う → --dump-config で設定検出を確認 → 影響を受けるカテゴリを特定し、関連する references/0X.md ガイドを参照 → 最小限の設定で隔離されたオプションをテスト

トリガー 5: スタイルオプションの問い合わせ → 質問をカテゴリにマッピング: ブレース→03、インデント→04、スペーシング→05、アライメント→01、改行→02 → references/ 内の特定のカテゴリガイドを参照 → 該当する場合は quick-reference.md から例を提供

トリガー 6: 影響を最小限に抑えるリクエスト → 「既存のコードスタイルの分析」ワークフローを使用して現在のパターンに一致させる → 変更を最小限にするために最も近いテンプレートから開始することを強調 → プロジェクト全体に適用する前に代表的なサンプルでテスト → どのパターンが保持され、どのパターンが正規化されたかを文書化

バンドルリソース

設定テンプレート (assets/configs/)

一般的なシナリオに最適化された、すぐに使える 7 つの .clang-format テンプレート:

• google-cpp-modified.clang-format - Google C++ スタイル、4スペースインデント、120桁制限
• linux-kernel.clang-format - Linux カーネルコーディング標準（タブ、K&R ブレース）
• microsoft-visual-studio.clang-format - Microsoft/Visual Studio 規約
• modern-cpp17-20.clang-format - 現代的な C++17/20 スタイル、最新イディオム
• compact-dense.clang-format - スペース制約のある環境向けコンパクトスタイル
• readable-spacious.clang-format - 可読性を重視したゆったりスタイル
• multi-language.clang-format - 多言語設定（C++、JavaScript、Java）

テンプレートを使用すべき場合: 新しいプロジェクトを開始する時、チーム標準を確立する時、フォーマットアプローチをすばやくテストする時。

統合スクリプト (assets/integrations/)

3つのエディタおよび Git 統合スクリプト:

• pre-commit - ステージングされたファイルを自動フォーマットする Git フックスクリプト（pre-commit または prek フレームワークで動作）
• vimrc-clang-format.vim - 保存時フォーマット用 Vim 設定
• emacs-clang-format.el - clang-format 統合用 Emacs 設定

統合を使用すべき場合: 開発ワークフローに自動フォーマットを設定する時。

注: pre-commit フックスクリプトは、pre-commit フレームワーク（Python）と prek（Rust 代替）の両方で動作します。どちらのフレームワークも .pre-commit-config.yaml を同じ構文で使用します。

リファレンスドキュメント (references/)

カテゴリ別に整理された詳細なドキュメント:

クイックナビゲーション:

• index.md - 概要とドキュメントハブ
• quick-reference.md - 説明付きの完全な動作設定
• cli-usage.md - コマンドラインの使用法、エディタ設定、CI/CD 統合

オプションカテゴリ (01-09.md):

1. 01-alignment.md - 宣言、代入、演算子の垂直アライメント
2. 02-breaking.md - 改行と折り返しルール
3. 03-braces.md - ブレース配置スタイル（K&R、Allman、GNU など）
4. 04-indentation.md - インデントルールと特殊ケース
5. 05-spacing.md - 演算子、キーワード周辺の空白制御
6. 06-includes.md - include/import の整理とソート
7. 07-languages.md - C++、Java、JavaScript の言語固有オプション
8. 08-comments.md - コメントのフォーマットとリフロー
9. 09-advanced.md - ペナルティシステム、生文字列フォーマット、実験的機能

完全リファレンス (complete/):

• clang-format-cli.md - 完全なコマンドラインインターフェースドキュメント
• clang-format-style-options.md - 194 すべてのスタイルオプションと例

一般的なワークフロー

テンプレートから新しい設定を作成

新しい .clang-format ファイルを作成するには:

1. 要件を特定する（スタイルガイド、チームの好み、言語）
2. assets/configs/ から最も近いテンプレートを選択する
3. テンプレートをプロジェクトルートに .clang-format としてコピーする
4. フォーマットをテストする: clang-format --dry-run file.cpp
5. 必要に応じて references/01-09.md を使用して特定のオプションをカスタマイズする
6. 変更を確認する: clang-format file.cpp | diff - file.cpp

例:

# Google C++ テンプレートをコピー
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# サンプルファイルでテスト
clang-format --dry-run /path/to/project/src/main.cpp

# 満足したら適用
clang-format -i /path/to/project/src/*.cpp

既存のコードスタイルの分析

既存のコードに一致する設定を生成するには:

1. コードサンプルを調査してフォーマットパターンを確認する
2. 主要な特性を特定する:
   • ブレース配置 → references/03-braces.md を参照
   • インデント（スペース/タブ、幅） → references/04-indentation.md を参照
   • スペーシング（演算子、キーワード） → references/05-spacing.md を参照
   • 改行（桁制限、折り返し） → references/02-breaking.md を参照
   • アライメントパターン → references/01-alignment.md を参照
3. パターンを references/quick-reference.md の最も近いベーススタイルにマッピングする
4. assets/configs/ の該当テンプレートから開始する
5. 観察されたパターンに合わせて特定のオプションを上書きする
6. 代表的なコードサンプルでテストする
7. フォーマットが既存のスタイルと一致するまで反復する

このワークフローは、既存のプロジェクトに clang-format を導入する際の空白のみの変更を最小限に抑えます。

エディタ統合のセットアップ

エディタで保存時フォーマットを有効にするには:

Vim:

1. assets/integrations/vimrc-clang-format.vim の内容を .vimrc にコピーする
2. Vim を再起動するか、設定を読み込む (source ~/.vimrc)
3. C/C++/Java ファイルを保存するとフォーマットがトリガーされる

Emacs:

1. assets/integrations/emacs-clang-format.el を Emacs 設定にコピーする
2. Emacs を再起動するか、評価する
3. サポートされているファイルを保存するとフォーマットがトリガーされる

その他のエディタ: VS Code、CLion、その他のエディタ設定については references/cli-usage.md を参照してください。

フォーマット用 Git フックのセットアップ

オプション 1: pre-commit/prek フレームワークの使用（推奨）:

.pre-commit-config.yaml で設定:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

次にインストール: pre-commit install または prek install

オプション 2: 手動 Git フック:

1. assets/integrations/pre-commit を .git/hooks/pre-commit にコピーする
2. 実行可能にする: chmod +x .git/hooks/pre-commit
3. 変更をステージングしてコミットしテストする

このフックはステージングされたファイルのみをフォーマットし、ステージングされていない変更は保持します。

フォーマット問題のトラブルシューティング

フォーマットが予期しない結果を生じた場合:

1. 設定の検出を確認する: clang-format --dump-config file.cpp
2. references/cli-usage.md でコマンドオプションを確認する
3. 影響を受けるフォーマットカテゴリを特定する（ブレース、スペーシング、改行など）
4. references/01-09.md の該当カテゴリガイドを参照する
5. 隔離されたオプションをテストする: 問題のオプションのみを含む最小限の設定を作成する
6. 包括的なオプション詳細については references/complete/clang-format-style-options.md を確認する

CI/CD フォーマットチェックのセットアップ

継続的インテグレーションでフォーマットを強制するには:

1. references/cli-usage.md の CI 例を確認する
2. パイプラインに clang-format チェックを追加する:

   # ファイルを変更せずにフォーマットをチェック
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. フォーマット違反があった場合にビルドが失敗するように設定する
4. コントリビューター向けにフォーマット要件を文書化する

主要コンセプト

ベーススタイル: 事前定義された設定（LLVM、Google、Chromium、Mozilla、WebKit、Microsoft、GNU）が出発点を提供します。BasedOnStyle: Google で設定し、特定のオプションを上書きします。

多言語サポート: 単一ファイル内で Language: キーを使用して異なる言語を個別に設定できます。例については assets/configs/multi-language.clang-format を参照してください。

ペナルティシステム: clang-format はペナルティを使用してフォーマットの代替案を選択します。ペナルティ値が高いほど、特定の選択肢が抑制されます。詳細は references/09-advanced.md を参照してください。

段階的改良: 要件に最も近いテンプレートから開始し、段階的にカスタマイズします。代表的なコードサンプルで頻繁にテストします。

設定のテスト

# ファイルを変更せずに変更をプレビュー
clang-format --dry-run file.cpp

# 提案された変更の差分を表示
clang-format file.cpp | diff - file.cpp

# ファイルにフォーマットを適用
clang-format -i file.cpp

# プロジェクト全体をフォーマット
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# CI でフォーマットをチェック（違反時は失敗）
clang-format --dry-run --Werror src/**/*.{cpp,h}

ナビゲーション戦略

ほとんどのタスクでは、次の進行に従ってください:

1. テンプレートから開始: assets/configs/ を参照してすぐに使える設定を見つける
2. クイックリファレンス: references/quick-reference.md で説明付きの完全な設定を確認する
3. カテゴリガイド: 特定のオプションカテゴリについては references/01-09.md を参照する
4. CLI 使用法: コマンドラインと統合の詳細は references/cli-usage.md を参照する
5. 完全リファレンス: 網羅的なオプションドキュメントは references/complete/ を使用する

コード分析やトラブルシューティング時には、フォーマットの側面（ブレース、スペーシング、アライメントなど）を特定し、references/ 内の該当カテゴリガイドに直接ジャンプしてください。