NetBeans Checkstyle¶
Checkstyleは、Javaソースコードを静的解析し、ルールに違反している箇所を検出するツールです。
リリース¶
| バージョン | リリース日 | 概要 |
|---|---|---|
| 4.1.0 | 2016-02-09 | Checkstyle 6.15を内蔵 |
| 4.0.0 | 2015-06-19 | Checkstyle 6.7を内蔵、JDK 7以上、Java SE 8新文法対応 |
| 3.4.0 | 2014-04-01 | Checkstyle 5.7を内蔵 |
| 3.3.0 | 2013-07-01 | Checkstyle 5.6を内蔵 |
インストール¶
Checkstyle Beansプラグインをインストールします。オンラインとオフラインのインストール手段が用意されています。
オンラインインストール¶
Checkstyle Beansダウンロードサイト のオンラインインストールの手順に従います。
- NetBeansの[ツール]メニュー > [プラグイン]で「プラグイン」ダイアログを開きます。
- 「プラグイン」ダイアログの[設定]タブを選択し、[追加]ボタンを押し「アップデート・カスタマイズ・センター」ダイアログを開きます。
- 「アップデート・カスタマイズ・センター」ダイアログで、名前欄とURL欄に次を記載します。
- 名前：Checkstyle Beans
- URL：http://www.sickboy.cz/checkstyle/autoupdate/autoupdate-3.xml
- 「アップデート・カスタマイズ・センター」ダイアログの[OK]ボタンを押し、「プラグイン」ダイアログのアップデート・センターの構成に追加されたことを確認します。
- 「プラグイン」ダイアログの[使用可能なプラグイン]タブを選択し、次の2つのプラグインにチェックを付け[インストール]ボタンを押します。
- Checkstyle Beans Library
- Checkstyle Beans Plugin
オフラインインストール¶
あらかじめ、Checkstyle Beansダウンロードサイト から次のアーカイブファイルをダウンロードします。
- netbeans-checkstyle-4.1.0-bin.zip
ダウンロードしたアーカイブファイルを一時作業領域に展開すると、次のNetBeansモジュールファイルが解凍されます。
- netbeans-checkstyle-library-4.1.0.nbm
- netbeans-checkstyle-plugin-4.1.0.nbm
- NetBeansの[ツール]メニュー > [プラグイン]で「プラグイン」ダイアログを開きます。
- 「プラグイン」ダイアログの[ダウンロード済]タブを選択し、[プラグインの追加]ボタンを押し、上述のNetBeansモジュールファイル2つを選択します。
- [開く]ボタンを押すと、「プラグイン」ダイアログに次の2つのプラグインが表示されます。
- Checkstyle Beans Library
- Checkstyle Beans Plugin
- インストールにチェックを付けて[インストール]ボタンを押します。
設定¶
デフォルトの設定は、かなり強烈¶
Checkstyle Beansプラグインをインストールして再起動すると、ソースコードの検査がバックグラウンドで実行されるようになります。
そして、Checkstyleの検査に引っかかった行にマークが付きます。デフォルトで検査するルールがかなり強烈なので、最初はCheckstyleの警告ばかりになってしまいます。
- 引数にfinalがない
- staticメソッドしかないクラスのデフォルトコンストラクタがprivateでない
- 行末に空白文字がある
- javadoc形式コメントがない（クラス、メソッド、フィールドとも）
- フィールド名を隠ぺいする引数・ローカル変数
そこで、検査項目はなるべく少なく必要最小限に絞ります。
設定部位¶
[ツール]メニュー > [オプション]で、[その他]ボタンを押し、[Checkstyle]タブを選択します。
適用ルールの設定¶
「オプション」ダイアログのCheckstyle設定ウィンドウで、Configuration File欄に適用するルールを指定したXMLファイルを指定します。
Checkstyle Beansプラグインには適用ルールを指定したXMLファイルはないので、checkstyle 本家のサイトのリポジトリから雛形を入手します。
https://github.com/checkstyle/checkstyle/tree/master/src/main/resources
2015-09-03現在、ここにはgoogle_checks.xmlとsun_checks.xmlが存在します。
ここから、sun_checks.xmlをダウンロードし、任意の場所（例えば、%USERPROFILE% ディレクトリ下に.checkstyleフォルダを作成）に配置します。適宜修正して、前述の「オプション」ダイアログのCheckstyle設定から指定します。
環境変数が使えないかいくつか試してみましたが、いずれの記述においても、指定したファイルがないとエラーになってしまいました。- USERPROFILE
- $USERPROFILE
- ${USERPROFILE}
ルール変更点の例¶
sun_checks.xmlをカスタマイズしていきます。
ソースファイルの文字コードを明示的に指定します。指定しない場合のデフォルトはシステムプロパティ file.encoding となるので、checkstyleを実行するプラットフォームによって異なる文字コードとなる可能性があります（Windows日本語版では、システムプロパティ file.encodingの値はMS932）。
<module name="Checker">
+ <property name="charset" value="UTF-8"/>
以下は空白文字に続いて改行コードでその行が終わっている場合、無駄な空白文字があると指摘するルールです。自動インデントの働くIDEでコーディングしていると、改行コードを打つと次の行が自動でインデント（空白文字等が適切なインデントレベルになるよう埋められる）されるため、IDEで空行を設けるとこのルールに抵触します。そこで、このルールは除外します。
- <module name="RegexpSingleline">
- <property name="format" value="\s+$"/>
- <property name="minimum" value="0"/>
- <property name="maximum" value="0"/>
- <property name="message" value="Line has trailing spaces."/>
- </module>
以下はJavadoc形式コメントを必須とする型、メソッド、変数を指定します。
スコープとしてprotected、publicである型、メソッド、変数についてはJavadoc形式コメントがあることを検査します。
! <module name="JavadocMethod">
+ <property name="scope" value="protected"/>
+ </module>
! <module name="JavadocType">
+ <property name="scope" value="protected"/>
+ </module>
! <module name="JavadocVariable">
+ <property name="scope" value="protected"/>
+ </module>
以下はJavadoc形式コメントで、最初の一文に文末記号（ピリオドまたは読点）があることの検査を除外します（Checkstyleが読点を判読できないので）。
! <module name="JavadocStyle">
+ <property name="checkFirstSentence" value="false"/>
+ </module>
以下は1行の桁数最大を規定するルールです。デフォルトは80桁と短いので、コーディング規約等の基準値に変更します（ここでは136桁を指定）。
! <module name="LineLength">
+ <property name="max" value="136"/>
+ </module>
- <module name="HiddenField"/>
以下はコード中で即値を使っていると指摘するルールです。さすがに厳しいので除外します。
- <module name="MagicNumber"/>
以下は、実装を持つメソッドをサブクラスでオーバーライドすると指摘するルールです。これも厳しいので除外します。
- <module name="DesignForExtension"/>
以下は、メソッドの引数がfinal付きでないと指摘するルールです。コーディング規約で引数に必ずfinalを付ける運用をしていない場合は除外します。
- <module name="FinalParameters"/>
以下は、定数のフィールド名が英大文字と数字、アンダースコアでない命名を指摘するルールです。
NetBeans IDEのデフォルトのヒントで定数命名規則が有効になっているので、互いの検査が競合しています。CI環境で検査対象とするならCheckstyleのルールを残し、そうでなければNetBeans IDEの定数命名規則を残しておくのがよいでしょう。
定数ではないがstatic finalがふさわしいフィールドもあり（例、クラス毎に定義するロガー）、この命名が指摘にあがってしまいます。
そこで、変数名がlogまたはloggerを許容するように定義をカスタマイズします。
- <module name="ConstantName"/>
+ <module name="ConstantName">
+ <property name="format"
+ valude="^log(ger)?|[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$"/>
+ </module>
以下は、フィールド名と同じ引数名またはローカル変数名を使用し、フィールド名が隠蔽されていることを指摘するルールです。
データを保持するDTO的なクラスでは、フィールド名のsetterメソッドの引数でフィールド名と同じ名前の引数を使用するコーディングが割と多くみかけられるので、この指摘を除外します。
- <module name="HiddenField"/>
- charsetプロパティの定義はTreeWalkerからCheckerへ移行しています。
- Checkstyle 5.6では、DoubleCheckedLockingが廃止になっています。
除外パスの設定¶
Checkstyleの検査対象から除外するパスを指定します。テストコードが一例です。
「オプション」ダイアログのCheckstyle設定で、Ignored Paths Pattern欄に次を指定します。
(^.*[\\/]test[\\/].*$)|(^.*Test\.java$)
階層ディレクトリの中にtestというディレクトリがあるもの、あるいはファイル名がTest.javaで終わるものを対象外としています。
設定した内容の保存先¶
次のファイルに設定内容が保存されています。
APPDATA\NetBeans\8.0\config\Preferences\cz\sickboy\netbeans\checkstyle.properties
8.0の部分は、NetBeansのバージョンによって変わります。
cz.sickboy.netbeans.checkstyle.customFile=C:\\Users\\torutk\\.checkstyle\\sun_checks.xml cz.sickboy.netbeans.checkstyle.customProperties= cz.sickboy.netbeans.checkstyle.customPropertyFile= cz.sickboy.netbeans.checkstyle.ignoredPathsPattern=(^.*[\\\\/]test[\\\\/].*$)|(^.*Test\\.java$) cz.sickboy.netbeans.checkstyle.severity=IGNORE cz.sickboy.netbeans.checkstyle.updated=true
特定箇所での検出の抑制¶
静的検証ツールは設定された条件に合致した箇所を検出するので、実際には品質に問題はないが検出された箇所については以後検出されないよう抑制する手段が必要です。
Checkstyleでは、次の2種類の抑制方法を用意しています。
- 検出抑制定義ファイルに抑制箇所を定義
ソースコードとは別に、検出を抑制する箇所の情報を記述したファイルを用意してその箇所では検出が上がらないようにする方法 - 特定のコメントでソースコード中の抑制箇所を定義
- アノテーション@SuppressWarnings でソースコード中の抑制箇所を定義
1.は抑制定義ファイルのパス指定が厄介です（複数共同開発では特に）。
2.は一番柔軟に箇所を指定できますが、抑制ルールを指定できないので複数行を抑制するときに全ルールが抑制されます。
3.はクラスまたはメソッドにアノテーションで抑制ルールを指定します。特定の行には指定できないのでメソッドやクラス単位で指定ルールが抑制されます。
検出抑制定義ファイルの設定¶
まずルール定義ファイルに、抑制定義ファイルを参照する設定を追記します。
<module name="Checker">
:
<module name="SuppressionFilter">
<property name="file" value="C:/Users/torutk/netbeans/checkstyle-suppressions.xml"/>
</module>
</module>
抑制定義ファイルのパスは絶対パスで記述する他、相対パスで記述することも可能です。ただし、NetBeans上でCheckstyleを実行する場合、相対パスの基点はNetBeans自身の実行時のカレントディレクトリ（Windows版では、およそC:\Program Files\NetBeans x.x）です。
検出抑制定義ファイル（ここではcheckstyle-suppressions.xml）には抑制したいルールと箇所を記述します。
<?xml version="1.0"?>
<!DOCTYPE suppressions PUBLIC
"-//Puppy Crawl//DTD Suppressions 1.0//EN"
"http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
<suppressions>
<suppress .../>
:
</suppressions>
suppressの記述例
- ファイル名がXXFacade.javaであるソースコードでは引数名の検出を抑制する
<suppress checks="ParameterName" files=".*Facade.java"/> - ファイル名がXXData.javaで25行目から38行目はJavadocコメントの検出を抑制する
<suppress checks="JavadocStyleCheck" files=".*Data.java" lines="25-38">
特定のコメント¶
まずルール定義ファイルに、コメントによる抑制の設定を追記します。
コメントの指定方法にはいくつかありますが、ここでは SuppressWithNearbyCommentFilter を使用します。
<module name="Checker">
:
<module name="TreeWalker">
<module name="FileContentsHolder"/>
</module>
<module name="SuppressWithNearbyCommentFilter">
<property name="commentFormat" value="SUPPRESS CHECK"/>
</module>
</module>
- 注）Checkstyle 8.2以降では、FileContentsHolderが廃止されています。今後Checkstyle BeansがバージョンアップしCheckstyle 8.2以降を内蔵する場合は当該行を削除します。
特定のパターンのコメント付与行が検出抑制されます。
private int array[]; // SUPPRESS CHECK
- 注）commentFormatを省略時、デフォルトの
SUPPRESS CHECKSTYLEとなるはずが Checkstyle Beans 4.1.0では効かなかった
操作¶
Checkstyleの実行¶
ユーザーが明示的に操作するUIは用意されていません。バックグラウンドで自動でチェックを行い、検出した行にマークが付きます。
