Introducing StyleCop on Legacy Projects using StyleCop for ReSharper
Recently, I've been working with introducing StyleCop on some legacy projects using the StyleCop for ReSharper plug-in.
This Blog aims to collect my findings, and also give some idea of what one can expect from using ReSharper to achieve StyleCop compliance.
First, I'll go thru how I auto-cleaned issues in one project, and after that I'll give some numbers from a complete solution.
A Single Legacy Project
The single legacy project was a measly 16 .cs files big, of which 2 were designer files. Just turning StyleCop onto this yielded 370 issues.
While this may come off as deterring at first, this blog is about how to use StyleCop for ReSharper to bring that down considerably.
Excluding designer files and generated files
Since Visual Studio .Designer.cs files aren't StyleCop compliant (no VS templates are) you probably want to exclude those from StyleCop.
These are your options:
- Doing it project-wide from the "Detailed Settings" on the "Rules" tab of the StyleCop Project Settings.
- Setting it per designer file by including a
//<auto-generated />
comment in the file header.
Handling Documentation Issues
First of all, you need to decide on how to handle the documentation issues, which normally will account for around half the warnings.
These are your options:
- Temporarily turn off all StyleCop rules but the documentation rules, and remedy those manually before going ahead with cleaning up the rest of the code.
- Permanently turn off all StyleCop documentation rules, and concentrate on the code.
- Auto-generate documentation tags by doing a "Code Cleanup" with all documentation cleanup modules enabled.
I would not recommend number three, as it will pollute your code with less-than-meaningful documentation comments.
Handling Header Formatting Documentation Issues
StyleCop is quite strict on how the file header should be formatted. It needs to have the filename in a copyright element, and you're not allowed to wrap the header in a region, for example.
To fix the header, you have these options:
- If your policy dictates an StyleCop-incompatible header content, permanently disable StyleCop rules concerning file header.
- If your policy dictates you have a multi-line copyright + licence text, manually Copy+Paste a compliant file header into each file, applying the quick fix to update the file="" attribute of the copyright element.
- If your policy allows for a single-line copyright statement, let the Stylecop plugin create those for you on running Code Cleanup. Fill in 'Company Information' in the StyleCop Settings, enable "Update file header" and let the StyleCop plugin "Replace entire header" in the Code Cleanup settings.
Taking these measures brought down the number of issues to 302.
Configuring StyleCop Code Cleanup
You need to configure ReSharper to have the built-in Code formatting help auto-format for StyleCop compliance.
Fortunately, the StyleCop for ReSharper comes with a StyleCopCodeStyle.xml resharper codestyle export, that you can import from the ReSharper options dialog.
A couple of notes on applying the StyleCopCodeStyle.xml code styles:
- I set "Blank lines between using groups" to zero; otherwise I get the "usings should be sorted alphabetically" issue as the "sort usings" only do so within using groups.
- I set "Wrap Lines" to zero, as StyleCop really doesn't like that.
- And of course, you need re-specify your StyleCop and Code Cleanup settings for documentation and header file fixes as per above.
Running Code Cleanup
After running the Code Cleanup with these settings and rebuilt, I'm now down to 24 issues - less than a tentht of the original number of warnings.
Running Code Cleanup a second time and rebuilding yields 21 warnings, a third cleanup round gives 16, and finally, doing it a fourth time and rebuilding I land on 10 issues.
This odd behaviour is because each cleanup round only adresses one of several potential issues per code block, and in the process, they sometime introduce new issues.
So just run Code Cleanup and rebuild until the number of issues stabilizes.
While working with this, the StyleCop Fixes page is an invaluable resource to debug your ReSharper Code Cleanup settings.
Manual fixes
The last 10 issues were actual errors or issues where there isn't enough context for Code Cleanup to do automatic refactorings. All of them were easily remedied given the available ReSharper refactorings:
- SA1401: Public fields should be exposed thru properties – if there is a good reason for exposing public fields directly, this warning can be suppressed using the suppression quickfix.
- SA1305: No Hungarian notation-like variable names.
- SA1300: Function names should begin with upper-case letter.
All in all, there were automatic or semi-automatic fixes for all issues.
A Full Solution
For my second test, I used a production solution consisting of 26 projects, all with roughly the same code content as my single project.
Turning StyleCop on yielded 5500+ issues.
Fixing Designer files, Documentation and header issues brought this down to 2924 issues.
- If you want to set StyleCop settings (exclude documentation, no designer files et c) on the full solution, copy/move a suitable Settings.StyleCop into the solution directory. The default for StyleCop is to try and merge the local project Settings.Stylecop with the one in the parent directory.
Applying Code Cleanup iteratively took me down to 264, 261, 256 and finally 255 issues.
During both this test and the single project test I experienced 'hiccups' where a certain issue weren't fixed by a global Code Cleanup, but redoing it on the single file or using the quickfix would.
Conclusion
By using the StyleCop for ReSharper plugin, introducing StyleCop on legacy projects can be reasonably painless. The main part is to comply with the documentation rules; once these are handled, the issues remaining can be fixed reasonably simple and with a small amount of developer work, even for large solutions.
If you have questions, think there is something I've ommitted in this article or just want to share your experiences or good links with the world, please don't hesitate to comment.
Happy refactoring!
Stefan Andersson