C# Advent Calendar 2013 1日目です。
StyleCopについて
StyleCopはC#向けの静的コード分析ツールで、設定されたルールに基づいて、C#のソースコードを分析し、違反したコードがあった場合に警告を出します。
Microsoft Public License (MS-PL)の元公開されているOSSで、以下のCodePlexのサイトで公開されています。
StyleCopは主にコードの書き方、たとえば、中括弧の位置や、行間の空行の数、空白を入れる入れないと言ったコーディングスタイルに注目した静的分析ツールで、よく知られているFxCopがコンパイル後のバイナリに対して、その品質を確認するのに対して、ソースコードに対してそれ自身の品質を確認します。
これらはどちらかをかければ良いというわけではなくて、それぞれ視点が異なるので、出来るだけ両方ビルド時などに適応して、出力を確認するようにした方が望ましいでしょう。
StyleCopの分析内容は、基本的にResharperを使用することで、事前に確認自動修正できる内容でが多いのですが、Resharperの書式設定機能は必ずしも強制されるわけでもないし、忙しいと
コードクリーンアップを忘れてしまうかもしれないので、Resharperを導入していても、中央のリポジトリへのチェックイン前にはローカルで確認するようにした方がいいでしょう。(当然ビルドぐらいはその時でもするでしょうしね)
StyleCopAnalyzersについて(2016/07/10追記)
Visual Studio 2015向けにはコード分析にRoslynを使用し、設定管理やリアルタイムでのサジェスト・コード修正にVisual Studio Analyzerと言うVisual Studio 2015以降に搭載される静的コード分析インフラを使用したStyleCopAnalyzersの使用をお勧めします。
StyleCopAnalyzersの使用方法については、以下を参考にしてください。
ダウンロードとインストール
CodePlexのサイトより最新版をダウンロードしてインストールします。
http://stylecop.codeplex.com/releases/
2013/11/27現在の最新バージョンは4.7です。
MSIファイルをダウンロードしたらダブルクリックしてインストールします。
ライセンスに同意して次に進みます。
特に選択する内容もありません。
インストール後Visual Studio(VS)を初めて起動したときに、Resharperがインストールされている環境だと以下のようなメッセージが出てくるので、Yesを選択します。
StyleCopはResharperと連携がとれるようになっていて、分析結果からResharperの機能を使用してコード修正が行えるようになっています。具体的な内容は次の項で確認します。
StyleCopの使用
StyleCopを適応するには分析メニューでと書きたいところですが、分析メニューには出てこないので、プロジェクトを右クリックして、Run StyleCopを選択します。
分析結果は、エラー一覧に表示されます。
上の図は、コンソールアプリケーションのプロジェクトを新規作成し、何も手を加えていない状態ですが、この状態で44件警告が出ます。
また、この警告はResharperとも連携が取られています。
StyleCop適応後、Resharperコード分析機能のQuick-Fixに分析結果(下図でStyleCop Rule:となっている箇所)が表示され、Quick-Fixから実際にStyleCopのルールに沿ったコードの修正が可能になっています。
たとえば、一番上のルールSA1600を適用すると、下図のようにclassにXMLドキュメントが追加されます。
正直なところ静的分析ツールの分析結果にあわせてコードを修正していくのって結構苦痛だったりしますが、これははかどります。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
結果はこうなります。
また、今までの説明では直接プロジェクトファイルの中にtargetへのパスの記述をしていましたが、チーム開発などではProgram Filesではない場所にインストールしたりするでしょうから、以下のように自動ビルドツールから呼び出されるバッチファイルないなどで環境変数を設定し、その環境変数をプロジェクトファイル内で指定するようにした方が良いでしょう。
環境変数設定
StyleCopTargets=%enlistmentroot%\ExternalTools\StyleCop\v4.7\StyleCop.targets
プロジェクトファイル
StyleCopの設定
行やブロックの除外
行やブロック単位で特定のルールを除外したい場合には、ソースコードの除外したい箇所の直前に以下のような形で属性を追加します。
[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1600:ElementsMustBeDocumented", Justification = "抑制する理由を書く")]
ルールごとの属性の書き方はRules Guideに書かれています。
動作設定
StyleCopの初期設定はかなり厳しい内容となっているので、変更したい場合もあるでしょう。
まずはプロジェクトを右クリックしてStyleCop Settingsを選択します。
Rules
Rulesタブでは適応するルールを選択します。ここでチェックを入れたり、外したりで適応するルールを決定します。
また、各ルールの詳細はRules Guideをダウンロードするか、以下のサイトにまとめられています。
適応外の設定
個人的は以下のルールは適応外にしています。
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のオプション設定が追加されています。
Reset C# Code Style Optionボタンは、R#のスタイル設定をStyleCopの仕様でリセットします。
参考
MSDN マガジン October 2013 > ALM Rangers – StyleCop による静的コード分析の実装
InfoQ ホームページ ニュース StyleCop – MicrosoftのC#用スタイル強制ツール
まとめ
StyleCopを使い、コーディングスタイルをチーム内で整えることで、コードが読みやすくなります。また、マイクロソフト社内で検証済のベストプラクティスを学ぶことも出来ます。
StyleCopとResharperのタッグは非常に強力です。
FxCopも併用しましょう。どちらかでは無く、視点が違うので両方使いましょう。
さて、1日目なのでゆるふわな感じにしてみました。ではあと24日皆さんハリキッテどうぞ！！
コメント
RT @ishisaka: StyleCopの導入と使用: C# Advent Calendar 2013 1日目です。 http://t.co/cekj8n4cGh
[…] ・OPC Diary StyleCopの導入と使用 […]
文面から読み取れない部分があったので質問させてください。
適応外の設定のところです。
[…] 2013年のAdvent CalendarではStyleCopの紹介をさせていただきましたが、このStyleCopAnalyzersはそれの後継に当たります。 […]