Clang-Format

clang-format は、ソースレイアウトを作成者ごとの好みではなく、リポジトリのポリシーとして扱います。構文トークンストリームに基づいて対応言語を整形するため、インデント、折り返し、多くの空白に関する判断を再現できます。ただし、命名、API、所有権、動作の正しさを定義するものではないため、レビューでは引き続きそれらの意味的な問題を確認する必要があります。

リポジトリポリシーの確立 #

リポジトリのルートに .clang-format ファイルをコミットします。--style=file を指定すると、clang-format は各入力ファイルから親ディレクトリに向かって検索し、最も近い .clang-format または _clang-format を選択します。そのため、入れ子になったディレクトリでルートポリシーを意図的に上書きできますが、意図しない場所に置かれたファイルによって、そのサブツリーの結果が変わる可能性があります。

プリセットがデフォルト値を提供する場合でも、ベーススタイルを含む明示的な YAML を使用します。

yaml

---
BasedOnStyle: LLVM
IndentWidth: 4
ColumnLimit: 100
SortIncludes: CaseSensitive

LLVM、Google、Chromium、Mozilla、WebKit、Microsoft、GNU は組み込みのベーススタイルです。プリセット名は、安定したリポジトリポリシーではありません。新しい clang-format のバージョンでは、オプションが追加されたり、デフォルト値が変更されたりする可能性があるためです。clang-format --style=LLVM --dump-config でバージョン固有の完全な初期設定を生成し、内容を確認したうえで、意図したオプションをコミットします。バイト単位で同一の出力が必要な場合は、開発環境と CI 環境でフォーマッタのバージョンを固定します。明示的な設定によってバージョン間の整形差異は減らせますが、なくすことはできません。

Language: セクションは、特定の言語に対してデフォルトセクションを拡張します。

yaml

---
BasedOnStyle: LLVM
IndentWidth: 4
---
Language: Cpp
PointerAlignment: Left

標準入力または拡張子のないファイルの場合は、--assume-filename=example.cc を指定して、言語検出とリポジトリの探索が対象ソースに一致するようにします。

フォーマッタの呼び出し #

すべての呼び出しでコミット済みのポリシーを使用します。

bash

# ビルドまたはファイルリストで選択したファイル全体を書き換えます。
clang-format --style=file -i src/widget.cc include/widget.h

# 変更された行だけを書き換えます。この呼び出しでのオフセットはバイトオフセットです。
clang-format --style=file -i --offset=120 --length=400 src/widget.cc

# 変更せずに CI のファイルセットを検査します。
clang-format --style=file --dry-run --Werror src/widget.cc include/widget.h

エディタでは、保存時または明示的な整形コマンドの実行時に、--style=file を指定して clang-format を呼び出します。CI では同じ実行可能ファイルのバージョンを使用し、プロジェクトに関連する追跡対象ファイルだけを検査します。シェルのグロブでは入れ子になったディレクトリ内のファイルが除外され、シェルによって結果が異なる可能性があります。レビュー可能な CI スクリプトでは、Git またはビルドシステムからファイルリストを取得し、整形によって差分が生じる場合に失敗させることができます。

--style=file:/absolute/path/to/.clang-format は既知の単一ファイルを選択し、親ディレクトリの探索を回避します。生成ツールや、サブディレクトリによって変化してはならないモノレポのポリシーに使用します。

レイアウトとレビューの分離 #

特定のフォーマッタバージョン、ソース、設定、要求された範囲に対して、整形結果は決定的です。パッチを作成する前に実行し、導入時の一括整形は機能変更と分離します。これにより、レビュアーはレイアウト変更を無視でき、意味のある差分を読みやすく確認できます。

整形結果をコンパイラやセキュリティチェックとして扱わないでください。clang-format は include を並べ替えたり、改行位置を書き換えたりできますが、include を解決したり、コンパイルを検証したりすることはありません。例外的なレイアウトを保護する場合は、生成形式または表形式をポリシーで表現できないときに限り、文書化された clang-format off と clang-format on のコメントを使用します。ディレクティブの横に例外の理由を記載してください。