スポンサーリンク

StyleCopの導入と使用

C# Advent Calendar 2013 1日目です。

StyleCopについて

StyleCopはC#向けの静的コード分析ツールで、設定されたルールに基づいて、C#のソースコードを分析し、違反したコードがあった場合に警告を出します。

Microsoft Public License (MS-PL)の元公開されているOSSで、以下のCodePlexのサイトで公開されています。

http://stylecop.codeplex.com/

StyleCopは主にコードの書き方、たとえば、中括弧の位置や、行間の空行の数、空白を入れる入れないと言ったコーディングスタイルに注目した静的分析ツールで、よく知られているFxCopがコンパイル後のバイナリに対して、その品質を確認するのに対して、ソースコードに対してそれ自身の品質を確認します。

これらはどちらかをかければ良いというわけではなくて、それぞれ視点が異なるので、出来るだけ両方ビルド時などに適応して、出力を確認するようにした方が望ましいでしょう。

StyleCopの分析内容は、基本的にResharperを使用することで、事前に確認自動修正できる内容でが多いのですが、Resharperの書式設定機能は必ずしも強制されるわけでもないし、忙しいと
コードクリーンアップを忘れてしまうかもしれないので、Resharperを導入していても、中央のリポジトリへのチェックイン前にはローカルで確認するようにした方がいいでしょう。(当然ビルドぐらいはその時でもするでしょうしね)

StyleCopAnalyzersについて(2016/07/10追記)

Visual Studio 2015向けにはコード分析にRoslynを使用し、設定管理やリアルタイムでのサジェスト・コード修正にVisual Studio Analyzerと言うVisual Studio 2015以降に搭載される静的コード分析インフラを使用したStyleCopAnalyzersの使用をお勧めします。

StyleCopAnalyzersの使用方法については、以下を参考にしてください。

StyleCopAnalyzersの使い方

ダウンロードとインストール

CodePlexのサイトより最新版をダウンロードしてインストールします。

http://stylecop.codeplex.com/releases/
SnapCrab_NoName_2013-11-27_20-12-51_No-00

2013/11/27現在の最新バージョンは4.7です。

MSIファイルをダウンロードしたらダブルクリックしてインストールします。

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-15-32_No-00

ライセンスに同意して次に進みます。

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-15-43_No-00

特に選択する内容もありません。

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-16-6_No-00

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-16-39_No-00

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-17-8_No-00

SnapCrab_StyleCop 47470 Setup_2013-11-27_20-19-22_No-00

インストール後Visual Studio(VS)を初めて起動したときに、Resharperがインストールされている環境だと以下のようなメッセージが出てくるので、Yesを選択します。

SnapCrab_スタート ページ - Microsoft Visual Studio_2013-11-27_20-23-3_No-00_01

StyleCopはResharperと連携がとれるようになっていて、分析結果からResharperの機能を使用してコード修正が行えるようになっています。具体的な内容は次の項で確認します。

StyleCopの使用

StyleCopを適応するには分析メニューでと書きたいところですが、分析メニューには出てこないので、プロジェクトを右クリックして、Run StyleCopを選択します。

SnapCrab_ConsoleApplication20131127 - Microsoft Visual Studio_2013-11-27_20-38-19_No-00_01

分析結果は、エラー一覧に表示されます。

SnapCrab_ConsoleApplication20131127 - Microsoft Visual Studio_2013-11-27_20-40-25_No-00_01

上の図は、コンソールアプリケーションのプロジェクトを新規作成し、何も手を加えていない状態ですが、この状態で44件警告が出ます。

また、この警告はResharperとも連携が取られています。

StyleCop適応後、Resharperコード分析機能のQuick-Fixに分析結果(下図でStyleCop Rule:となっている箇所)が表示され、Quick-Fixから実際にStyleCopのルールに沿ったコードの修正が可能になっています。

SnapCrab_NoName_2013-11-27_20-43-38_No-00_01

たとえば、一番上のルールSA1600を適用すると、下図のようにclassにXMLドキュメントが追加されます。

SnapCrab_NoName_2013-11-27_20-51-45_No-00

正直なところ静的分析ツールの分析結果にあわせてコードを修正していくのって結構苦痛だったりしますが、これははかどります。Resharperすげーをここでも体感できます。

また、おわかりのように、StyleCopはちゃんとXMLドキュメントコメントが追加されているか、いないかまでは確認してくれますが、その内容までは確認してくれないので、そこは当然人間がコードレビューなどでコメント内容の善し悪しを判断しないとなりません。

MSBuildとの連系

VSから適応できるのは良いとして、ビルド時に自動実行して違反があればビルドを止めたいし、そもそもTFSやJenkinsなんかのCIツール使うときに適応したいのもそれはそうでしょうし、ということで、StyleCopもFxCopと同様にMSBuildとの連系機能を持っています。しかしながら、そこはGUIでチェックを入れるだけとは行かず、プロジェクトファイルを若干修正する必要があります。

先ず、プロジェクトファイル(.csproj)をエディタで開いて、以下のようなコメントの行を見つけます。


この直前に以下の行を追加します。1行目の記述がすでにあるようだったら、1行目だけは追加しなくて結構です。


 

2行目のパスは、環境とStyleCopのバージョンに依存しますので、適宜書き換えをお願いします。

この設定を書き換えてビルドすると以下のようにワーニングが出るようになります。

1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Program.cs(3,1): warning : SA1600 : CSharp.Documentation : The class must have a documentation header.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Program.cs(5,1): warning : SA1600 : CSharp.Documentation : The method must have a documentation header.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Program.cs(1,1): warning : SA1633 : CSharp.Documentation : The file has no header, the header Xml is invalid, or the header is not located at the top of the file.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Program.cs(9,1): warning : SA1508 : CSharp.Layout : A closing curly bracket must not be preceded by a blank line.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Properties\AssemblyInfo.cs(1,1): warning : SA1635 : CSharp.Documentation : The copyright tag in the file header must not be empty.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\Properties\AssemblyInfo.cs(1,1): warning : SA1640 : CSharp.Documentation : The copyright tag in the file header must contain a company attribute which contains the name of the company.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\obj\Debug\TemporaryGeneratedFile_E7A71F73-0F8D-4B9B-B56E-8E70B10BC5D3.cs(1,1): warning : SA1633 : CSharp.Documentation : The file has no header, the header Xml is invalid, or the header is not located at the top of the file.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\obj\Debug\TemporaryGeneratedFile_036C0B5B-1481-4323-8D20-8F5ADCB23D92.cs(1,1): warning : SA1633 : CSharp.Documentation : The file has no header, the header Xml is invalid, or the header is not located at the top of the file.
1>D:\work\src\ConsoleApplication20131127\ConsoleApplication20131127\obj\Debug\TemporaryGeneratedFile_5937a670-0e60-4077-877b-f7221da3dda1.cs(1,1): warning : SA1633 : CSharp.Documentation : The file has no header, the header Xml is invalid, or the header is not located at the top of the file.

また、StyleCopの分析結果でコンパイルエラーとしたい場合には、プロジェクトファイルに

false

を追加します。

追加場所については以下を参考にして下さい。以下の例では14行目です。



  
  
    Debug
    AnyCPU
    {98A05456-A314-4C0F-92AD-E9DFA3FC7D4F}
    Exe
    Properties
    ConsoleApplication20131127
    ConsoleApplication20131127
    v4.5
    512
    false
  

結果はこうなります。

SnapCrab_NoName_2013-11-27_21-34-9_No-00

また、今までの説明では直接プロジェクトファイルの中にtargetへのパスの記述をしていましたが、チーム開発などではProgram Filesではない場所にインストールしたりするでしょうから、以下のように自動ビルドツールから呼び出されるバッチファイルないなどで環境変数を設定し、その環境変数をプロジェクトファイル内で指定するようにした方が良いでしょう。

環境変数設定

StyleCopTargets=%enlistmentroot%\ExternalTools\StyleCop\v4.7\StyleCop.targets 

プロジェクトファイル

  
  

この項参考: http://stylecop.codeplex.com/wikipage?title=Setting%20Up%20StyleCop%20MSBuild%20Integration&referringTitle=Documentation

StyleCopの設定

行やブロックの除外

行やブロック単位で特定のルールを除外したい場合には、ソースコードの除外したい箇所の直前に以下のような形で属性を追加します。

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1600:ElementsMustBeDocumented", Justification = "抑制する理由を書く")]

ルールごとの属性の書き方はRules Guideに書かれています。

動作設定

StyleCopの初期設定はかなり厳しい内容となっているので、変更したい場合もあるでしょう。

まずはプロジェクトを右クリックしてStyleCop Settingsを選択します。

SnapCrab_ConsoleApplication20131127 - Microsoft Visual Studio_2013-11-27_23-16-10_No-00_01

Rules

Rulesタブでは適応するルールを選択します。ここでチェックを入れたり、外したりで適応するルールを決定します。

SnapCrab_StyleCop 47 (47470) Project Settings - DworksrcConsoleApplication20131127ConsoleApplication20131127S_2013-11-27_23-19-19_No-00

また、各ルールの詳細はRules Guideをダウンロードするか、以下のサイトにまとめられています。

Forbidden
適応外の設定

個人的は以下のルールは適応外にしています。

SA1628 DocumentationTextMustBeginWithACapitalLetter
SA1629 DocumentationTextMustEndWithAPeriod
SA1630 DocumentationTextMustContainWhitespace
SA1650 ElementDocumentationMustBeSpelledCorrectly
これらはxmlドキュメントコメントで日本語を使ったときに警告を出すので外しています。

Documentation Rules/File Headersは標準のヘッダが気に入らないのであれば丸ごと外してもかまわないと思います。

SA1200 UsingDirectivesMustBePlacedWithinNamespace
これはusing句をnamespaceの中へ移動させるルールですが、意図はわかるものの、外してしまっても良いかと思います。(外しています)

SA1124 DoNotUseRegions
regionがいっぱいあるコードは本当に読みやすいでしょうか?

Settings Files

Setting Filesタブでは設定ファイルの参照関係を設定します。

StyleCopはプロジェクトのフォルダにSettings.StyleCopと言うファイルをつくって設定内容を保存しますが、このタブでは参照するファイルとのマージ設定が出来るようになっています。

Do not merge with any other setting filesはローカルの設定ファイルだけを使用します。
Merge with settings file found in parent foldersはローカルとその親ディレクトリとの間で設定をマージします。つまり、ソリューションで設定を共有する場合にこの設定にします。
Merge with the following setting fileはパス設定した設定ファイルとの間で設定をマージします。チームで共有する場合などではこの設定すると良いと思います。

詳細は以下を参照して下さい。
http://stylecop.codeplex.com/wikipage?title=Sharing%20StyleCop%20Settings%20Across%20Projects&referringTitle=Documentation

Company Information

Company Informationタブはファイルヘッダーで使用する会社名と著作権表記を設定します。

Hungarian

Hungarianタブでは、プロジェクトで使用して良いハンガリアン記法の接頭句を指定します。StyleCopでは標準ではSA1305 FieldNamesMustNotUseHungarianNotationルールによって、強制的にハンガリアン記法は違反とされますが、このタブで設定された2文字が変数の頭に付けられている場合には見逃されます。

ルールの追加

ルールを追加したい(なんと奇特な!)場合には、コードを書いてDLLを作り決められたフォルダに置くという手順になります。

詳しくは以下のドキュメントがわかりやすいと思いますので参考にして下さい。

C# Code Reviews using StyleCOP
http://www.dotnetspark.com/kb/500-c-sharp-code-reviews-using-stylecop.aspx

Resharper

ResharperにもStyleCopのオプション設定が追加されています。

SnapCrab_Options_2013-11-28_22-35-16_No-00

Reset C# Code Style Optionボタンは、R#のスタイル設定をStyleCopの仕様でリセットします。

参考

MSDN マガジン October 2013 > ALM Rangers – StyleCop による静的コード分析の実装

InfoQ ホームページ ニュース StyleCop – MicrosoftのC#用スタイル強制ツール

漫坊亭@ウィキ

まとめ

StyleCopを使い、コーディングスタイルをチーム内で整えることで、コードが読みやすくなります。また、マイクロソフト社内で検証済のベストプラクティスを学ぶことも出来ます。

StyleCopとResharperのタッグは非常に強力です。

FxCopも併用しましょう。どちらかでは無く、視点が違うので両方使いましょう。

さて、1日目なのでゆるふわな感じにしてみました。ではあと24日皆さんハリキッテどうぞ!!

コメント

  1. […] ・OPC Diary  StyleCopの導入と使用 […]

  2. nkns より:

    文面から読み取れない部分があったので質問させてください。
    適応外の設定のところです。

    SA1124 DoNotUseRegions
    これはregionを記述した際に指摘されるのでしょうか。
    それとも記述しなかった際に指摘されるのでしょうか。
    「Do not use region=regionを使うな」
    だと思うのですが、このルールを適用しないということは
    regionの記述を許す、ということではないでしょうか。

    regionがいっぱいあるコードは本当に読みやすいでしょうか?
    regionの記述はしてほしくない、と読み取ったのですが
    であるならば、SA1124 DoNotUseRegionsのルールは適用しないといけないのではないでしょうか。

  3. […] 2013年のAdvent CalendarではStyleCopの紹介をさせていただきましたが、このStyleCopAnalyzersはそれの後継に当たります。 […]

タイトルとURLをコピーしました