Today I did something I’ve been hoping to do for a long time. I’ve set up a build step which performs styling checks against a code base which myself and a few others maintain. To do this I used StyleCop which analyses C# source files against a set of rules held in a XML file. I thought it would be good to write about why I think it’s an important build step.
Over the past couple of years I’ve spoken to developers about StyleCop and the feedback hasn’t been great and that’s understandable to a certain degree because the initial experience you get with StyleCop isn’t a pleasant one. It spews out thousands of warnings about code style violations and the corresponding rule ID. If you’re build system treats warnings as errors, such as mine, it’s even worse. It’s this initial shock to the system that put those developers off. After all, who wants to introduce a process which will give them more work to do? For me it’s about the long term gains.
What are the benefits?
If you’ve ever done code reviews before then hopefully this will resonate with you. I have worked in teams both large and small with the smallest being three developers, a medium team which ranged from 6 – 8 depending on workload and a large team (my last position which I was the lead) of about 25 – 30 developers. You can imagine the amount of time and energy which is spent on small things such as spelling mistakes, naming conventions, when and where to check for null, indentation rules, the list goes on. These sorts of “mistakes” if you want to call them that, are a complete waste of time and take focus away on what code reviews are all about. I understand there are coding conventions we all need to live by but code review should be about finding potential bugs and questioning and fostering discussions about a design decision, not telling someone that instance variables need to begin with an underscore.
Conventions and styling is something a tool such as StyleCop can check and which is automated. Although it won’t tell you how to name things (but can enforce rules such as “all Boolean properties must begin with ‘Is’”) it can check spelling, it can check indentation rules, it can check that comments are placed in certain areas of code, it can check that all if statements have curly braces. There are over a hundred rules which you can select and which I’m sure will fit right in with the coding guidelines of your team. There’s even a plugin called StyleCop+which have even more advanced naming rules.
The most important thing there is time and if you remove all possibilities of developers ever discussing styling and code formatting, then collectively think of how much pain you’ve taken away. Even if you shave 10 seconds off every code review or even every second or third code review for the life of the project, then there’s your return on investment. You’ve automated a boring task which ads quality to the code base without having to worry about someone forgetting to enforce the rules. This is true of all static analysis, not only styling.
It’s not all rainbows and unicorns though. You need to ensure that all developers are on board with this which can be a hard sell. Even if the team makes a decision collectively, those who resist probably won’t run the tool before checking in their code which is why it’s important to add StyleCop to your build process. Any violations break the build and notify the developers.
To make things a little easier you can configure StyleCop to check rules as a post build step, that way the project will fail compilation on the developers machine. This can be configured though. In our project StyleCop violations generate an error in Visual Studio which will prevent the application from running.
This might seem like too much burden to place on your team but it won’t take long for people to become comfortable with the process, and just think, you’ll never have to discuss styling and conventions again and developers will take more care when writing code.
Making things a little easier
If you don’t want to cause your team too much pain, you can set up StyleCop to only apply rules to new files which are added to your solution. This is the approach I took when introducing the tool. See here for more details.
As much as I love StyleCop, at some point I plan on removing it and favouring a tool which will auto-format all code when checked in and have it enforced at the server. This way, it does not matter what style a developer chooses to write in. When it’s checked in it’s formatted according to conventions and everyone can worry about more important things.
To get started with StyleCop check out the official project site. There’s tones of documentation their on how to get set up.