End the Style War - Make StyleCop the Bad Guy
When Edward Rowe and I started Red Blue Games we spent a lot of time getting familiar with C# and best practices in coding for Unity based games. Since both of us were new to C# we had the luxury of developing our own code style preferences as we went, relying on MonoDevelop’s clunky Policy System to make formatting our code to those preferences as automatic as possible.
But when our newest programmer, Kevin Mabie, joined we ran into a few problems that immediately challenged our system. First, coming with years of experience from a studio that used a very different code style, he had developed strong preferences for that style. This problem is something every studio will face; every programmer brings with them their own set of habits and preferences. Through school, previous jobs, or personal work, preferences are formed that are understandably difficult to give up.
The second problem we needed to tackle was that Kevin’s IDE of choice is Visual Studio, which meant having to sync up our policies between MonoDevelop and VS to avoid formatting files back and forth. So we decided this was a good time to recreate our company policy from the ground up. We pulled up a C# Style Guide that we could mostly agree on and went through item by item in what became a very painful four hour meeting at Starbucks as we debated the merits of curly bracket placement and variable name conventions. We emerged from the meeting feeling exhausted and beaten down, having jockeyed for pet preferences and compromised until no one was really happy.
We decided to try out the new policy, but without complete buy-in and automated processes in place, enforcing it became stressful and cumbersome. The built in IDE formatting features only catch a subset of the style requirements we had decided on and no one wanted to be the bad guy telling others to put periods after their comments. This is when we decided to outsource the policing to StyleCop, which is a tool that will error or warn whenever style violations are found.
Why do we care so much?
Perhaps you are reading this thinking, “What is code style?” or “Why does it matter so much?” Code style refers to all the choices a developer makes when writing code that won’t affect the behavior of the code but do affect the way it looks. Whitespace placement, variable naming, bracket placement, and comment use are all examples of style choices. Here are a few reasons why we should care to have a consistent, conventional, code style.
- Code in a familiar style is easier to read and comprehend
- Code that follows a consistent style is easier to contribute to or integrate into your own projects
- Code review is easier when not being tempted to comment on style
- Coders can focus on writing code instead of worrying about how it looks
- Catching errors in code will be easier if code patterns look similar
- Code ownership is less obvious and encourages teammates to collaborate more freely
I should also elaborate that consistent code style is especially important. Whatever style choices a team makes are less important than their consistency in following those choices because the majority of the benefits above come mostly from consistency. I’d recommend this article for a more thoughtful defense of code style guides.
What is StyleCop?
StyleCop is a tool born inside Microsoft that can be integrated into IDEs to scan code for style violations. Users can customize which rules are enforced and even create their own rules.
“many wars were fought over the nature of these rules, and much blood was shed” Jason Allor, Creator of StyleCop
The default rules were established by consolidating the preferences of various teams across Microsoft and are designed to emphasize readability and maintainability of C# code. When coming up with our own customizations we decided to use defaults unless we all agreed that a rule provided little value to our team. After all, part of the point of using the tool was to end the debates over style decisions by using the closest thing to an industry standard we could find.
StyleCop can be installed to work with Visual Studio and an Add-In allows it to be run within MonoDevelop as well.
Making StyleCop play Bad Cop
Immediately out of the gate there were rules that we weren’t used to following, but allowing the tool to set our style standards was liberating for the entire team. Our style choices were no longer up for debate and the entire team was finally on the same page. Furthermore, while adjusting to new style preferences can be frustrating, it took the personal nature of the arguments out of the equation by allowing the team to blame our frustrations on the tool instead of one another.
There are other more tangible benefits to using the tool as well. We catch errors earlier, generally at creation time, and are able to remove human error from both the writing and reviewing of code. StyleCop ensures that our methods’ comments are in sync with their parameters and return values, which helps keep our documentation from drifting too far.
The adoption of StyleCop has allowed our team to define and stick to a style that we’ve been using for the last year with little debate. Even if you have a defined style, it’s worth using a tool like StyleCop to enforce it. We’ll be writing up instructions for how we set up our own Unity project with StyleCop here soon.
