Checkstyle 導入とカスタマイズガイド

この記事では、Checkstyle を既存の Java プロジェクトに導入する方法、特に Maven を用いた導入手順、そして Google のチェックスタイル（google_checks.xml）をカスタマイズする方法について、できるだけ詳細に解説します。
この記事を参考に、プロジェクトのコード品質を一定に保ち、開発効率を向上させることを目的としています。

記事の内容がよければ「いいね」をお願いします！！

目次

はじめに
Checkstyle とは？
Maven での Checkstyle 導入
- Maven Checkstyle Plugin の設定
- Checkstyle のバージョン管理と注意点
Google Checks 設定ファイル (google_checks.xml) の概要
Google Checks のカスタマイズ方法
- ルールの有効・無効の切り替え
- 各ルールの severity（重大度）の変更
SuppressionFilter の使い方
よくあるトラブルシューティング
まとめ
参考情報

はじめに

Checkstyle は、Java のコード規約に沿ってソースコードの品質を自動的にチェックしてくれるツールです。
特に、大規模なプロジェクトではコードの書式統一が重要となるため、チェック自動化ツールとして多くの現場で利用されています。
この記事では、Maven を使った Checkstyle の導入手順や、Google のコーディング規約に基づく設定ファイル（google_checks.xml）のカスタマイズ方法について詳しく解説します。

Checkstyle とは？

Checkstyle は、Java コードの規約（命名規則、インデント、インポート順、コメントの書き方など）を自動的に検査するツールです。
チェック結果は、レポートやコンソール出力で確認でき、違反がある場合は開発者に注意を促すことができます。
また、チェックルールのカスタマイズが可能なため、プロジェクトごとのルールに合わせて柔軟に設定を変更できます。

Maven での Checkstyle 導入

Maven Checkstyle Plugin の設定

Maven プロジェクトに Checkstyle を導入する場合、まずは pom.xml に Maven Checkstyle Plugin を追加します。
以下は、その一例です。

<!-- pom.xml の build セクション内 -->
<build>
  <plugins>
    <plugin>
      <!-- Maven Checkstyle Plugin のグループID -->
      <groupId>org.apache.maven.plugins</groupId>
      <!-- Maven Checkstyle Plugin のアーティファクトID -->
      <artifactId>maven-checkstyle-plugin</artifactId>
      <!-- プラグインのバージョン（例：最新の 3.6.0 を利用する場合） -->
      <version>3.6.0</version>
      <configuration>
        <!-- Checkstyle の設定ファイルの場所 -->
        <configLocation>google_checks-9.3_embed_pdf.xml</configLocation>
        <!-- 違反があった場合にビルドを失敗させる -->
        <failOnViolation>true</failOnViolation>
        <!-- 使用する Checkstyle のバージョン（プロパティ経由で指定しても良い） -->
        <checkstyleVersion>9.3</checkstyleVersion>
      </configuration>
      <executions>
        <execution>
          <!-- Maven の validate フェーズで実行 -->
          <phase>validate</phase>
          <goals>
            <goal>check</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

上記の設定では、Maven の validate フェーズで Checkstyle を実行するようにバインドしています。
そのため、mvn clean package や mvn clean validate を実行すると、設定ファイルに基づいたコードチェックが行われます。

Checkstyle のバージョン管理と注意点

Checkstyle のバージョン
Checkstyle 10.x 系は JDK 11 以上が必要ですが、Java 8 環境では Checkstyle 9.x 系（例：9.3）を利用する必要があります。
Maven プラグインの設定で <checkstyleVersion>9.3</checkstyleVersion> と指定することで、適切なバージョンが利用されるようにします。
プラグインのバージョンアップ
Maven Checkstyle Plugin のバージョンによっては、かつて使用可能だったパラメータ（例：failureSeverity）がサポートされなくなっている場合があります。
最新バージョンでは、警告レベルの違反はビルド失敗とならない仕様になっているため、設定ファイル側で severity を調整する必要があります。

Google Checks 設定ファイル (google_checks.xml) の概要

Google の公式コーディング規約に基づく設定ファイル google_checks.xml は、以下のような特徴を持っています。

ルート要素: <module name="Checker">
すべてのチェックの親モジュールとして、ここに各種チェックルールが含まれます。
TreeWalker モジュール
<module name="TreeWalker"> 内に、具体的なコードチェック（インデント、改行、括弧の配置、インポート順など）のルールが定義されています。
その他の個別チェック
インポート文の順序、Javadoc の存在、命名規則など、細かいチェックが多数定義されています。

Google Checks の設定ファイルは、そのまま利用することもできますが、プロジェクトごとにルールの厳しさや適用箇所をカスタマイズすることも可能です。

google_checks.xmlのGitHubリポジトリ
GitHubのリポジトリです。ここからgoogle_checks.xmlをダウンロードできます。

左上の部分がmasterとなっていますが、使用するCheckStyleのバージョンに合わせることをお勧めします。
今回はJava8に導入するのでCheckStyleは9.3のバージョンを使用します。
よって左上の部分を9.3にします。

Google Checks のカスタマイズ方法

Google Checks の設定ファイルをカスタマイズすることで、プロジェクトのニーズに合わせたチェックルールを適用できます。
ここでは、いくつかの代表的なカスタマイズ方法を紹介します。

ルールの有効・無効の切り替え

特定のチェックルールがプロジェクトにそぐわない場合、以下のようにそのモジュールをコメントアウトまたは削除することで、チェック対象から除外できます。

<!-- 例: 不要なルールをコメントアウトする -->
<!--
<module name="JavadocMethod">
  <property name="scope" value="public"/>
</module>
-->

各ルールの severity（重大度）の変更

チェックスタイルのルールは、違反が発生した場合の「severity」が設定されています。
デフォルトでは "warning" になっている場合が多いですが、これを "error" に変更することで、違反がビルド失敗の原因となるようにできます。

<!-- 例: インポート順のチェックをエラーとして扱う -->
<module name="CustomImportOrder">
  <!-- severity を明示的に error に変更 -->
  <property name="severity" value="error"/>
  <!-- その他の設定 -->
  <property name="option" value="alphabetical"/>
  <property name="sortStaticImportsAlphabetically" value="true"/>
</module>

このように、各モジュール内に <property name="severity" value="error"/> を追加または修正することで、違反がエラーとして扱われ、ビルドが失敗するようになります。

SuppressionFilter の使い方

Checkstyle では、特定の違反を意図的に無視するために SuppressionFilter を利用することができます。
以下は、SuppressionFilter の設定例です。

<module name="SuppressionFilter">
  <!-- サプレッションファイルのパスを指定 -->
  <property name="file" value="${org.checkstyle.google.suppressionfilter.config}"
            default="checkstyle-suppressions.xml"/>
  <!-- サプレッションファイルが存在しない場合はエラーにする -->
  <property name="optional" value="false"/>
</module>

設定内容の詳細

file プロパティ
${org.checkstyle.google.suppressionfilter.config} はプロパティプレースホルダーで、Maven やシステムプロパティから値を上書き可能です。
デフォルト値は checkstyle-suppressions.xml となっており、プロジェクトルートにこのファイルを配置しておく必要があります。
optional プロパティ
optional を false に設定しているため、サプレッションファイルが存在しない場合はエラーとなります。
サプレッションファイルには、無視するルールやファイルパス、特定の行番号などを定義できます。

サプレッションを適用することで、どうしても一部のルール違反を無視したい場合に、柔軟な対応が可能になります。

よくあるトラブルシューティング

「Old version of checkstyle detected」警告
原因: Maven Checkstyle Plugin が古い Checkstyle を使用している場合、最新のルールが認識されない可能性があります。
対策:
- <checkstyleVersion> パラメータを用いてバージョンを指定する（例: 9.3）。
- Maven Checkstyle Plugin 自体のバージョンを最新にアップデートする（例: 3.6.0）。
「given name COMPACT_CTOR_DEF」エラー
原因: 設定ファイル内でモジュールの名前が単純名で記述され、正しく解決できない場合に発生します。
対策:
- 該当モジュール名を完全修飾名に変更する。
  例: com.puppycrawl.tools.checkstyle.checks.coding.CompactCtorDefCheck
- もしくは、使用する Checkstyle のバージョンに合わせて設定ファイル自体を最新版に更新する。
警告レベルの違反でビルドが失敗しない
原因: 最新の Maven Checkstyle Plugin では failureSeverity パラメータがサポートされなくなっているため、警告レベルの違反はビルド失敗の対象になりません。
対策:
- 設定ファイル内で、必要なルールの severity を error に変更する。
- もしくは、ビルドを失敗させたいチェックルールのみを有効にするようにカスタマイズする。

まとめ

この記事では、以下の内容について詳細に解説しました。

Checkstyle の基本概念と導入方法
Maven を利用してプロジェクトに Checkstyle を導入する手順と、設定ファイルの配置方法を説明しました。
Google Checks 設定ファイルの概要とカスタマイズ方法
Google のコーディング規約に基づく設定ファイルを利用し、ルールの有効・無効の切り替えや severity の変更方法について紹介しました。
SuppressionFilter の設定
不要な違反報告を抑制するためのサプレッションファイルの設定方法を詳しく解説しました。
トラブルシューティング
よくあるエラーや警告の原因と対策について、実例を交えて説明しました。

これらの知識を活用することで、プロジェクトごとに最適なコードチェック体制を構築し、開発品質の向上に役立てることができます。

参考情報

Checkstyle 公式サイト
Checkstyle の詳細なドキュメントや各モジュールの説明が掲載されています。
Maven Checkstyle Plugin 公式ドキュメント
Maven との連携方法や設定例が紹介されています。
Google Java Style Guide
Google の公式コーディング規約。Google Checks 設定ファイルのベースとなっています。
Checkstyle Config - Packages
モジュール名の指定方法や単純名と完全修飾名の違いについて解説されています。
google_checks.xmlのGitHubリポジトリ
GitHubのリポジトリです。ここからgoogle_checks.xmlをダウンロードできます。

この記事は、Checkstyle 導入に悩むエンジニアの参考資料として作成しました！
記事の内容がよければ「いいね」をお願いします！！