The more developers I meet, the more I realize that developers continue to make their own lives difficult. They simply accept that the environment they work in (technically) is all that they have. They don’t bother learning more advanced things about it, or even trying to customize it in any way. It’s even worse when an entire team chooses to just use the default environment and everybody is left on their own to do what they want to develop the product. Granted there is something to be said about just getting something out the door, but if you just open up your IDE and get coding without ever customizing it to how *you* code you’ll soon be running into headaches.
I may end up making this a series of posts so I can simply hand this out to future team members so they can understand how their life could be vastly improved. The first tool I’ll dig into is StyleCop.
If your team is doing manual code reviews (like every team does, right?) I strongly hope that the reviews don’t cover things about formatting the code or naming conventions. Make use of a tool that can enforce those rules for you automatically. This is especially important for a team of developers where everybody has different preferred programming languages. As an example, my current team consists of developers who have backgrounds in VB6, Clojure, Ruby, and Java. That alone is a plethora of patterns for how the code should be formatted. Because everybody’s background drives how they format their code going forward you can wind up with a lot of source code commits that are purely reformatting of code so the next developer can understand the code. Why waste the resources when you can have a tool tell the developer they aren’t following the rules of the team prior to even checking in?
There’s a lot of rules that some people that don’t agree with, but I’ve found good reasons for nearly every single rule that comes with StyleCop. One of the key things to do when using StyleCop is not to every change the default settings that are installed on the machine. StyleCop allows you to create a settings file for a folder (and all of its children folders) that override its parent. My general approach is that in the root of every project folder I place the Settings.StyleCop folder that should apply to every single project.
Now, in that base settings file, I typically change the following options:
- Options –> uncheck “Cache StyleCop analysis results”. I’ve yet to hit a project that takes a long time to analyze, so there’s no point in caching results.
- Settings File –> ensure that “Merge with settings file found in parent folders” is the selected option.
- Rules –> C# –> Detailed Settings –> check “Analyze generate files”. This way if you’re doing some sort XAML work, any XAML generate fields will be flagged as part of the naming conventions.
- Rules –> Documentation Rules –> Detailed Settings –> check “Ignore privates”, “Ignore internals” and uncheck “Include fields”. My main reasoning for turning off this level of documentation is that the classes should be very small and concise to adhere to the Single Responsibility Principle. If the class is so massive that you need to document your fields and all the private members, then you really should be having some lengthy conversations in your code review.
- Rules –> Documentations Rules –> Element Documentation –> Check SA1609, SA1610, SA1628, SA1629, and SA 1630. This way you have everything documented (a) for Intellisense, and (b) so anybody can look at the (hopefully up-to-date) documentation and know what to expect when working with the item.
- Depending on the team/project, I uncheck SA1600, SA1601, and SA1602. This way StyleCop doesn’t complain about having to document every public or protected element, but when there’s some level of documentation it must meet the criteria.
- Rules –> Documentation Rules –> File Headers –> Uncheck SA1633, and check SA1639. I don’t believe every file needs to have documentation about the file. The rest of the documentation should describe all of that pretty clearly. But again, if there is any level of documentation in the file header it needs to conform.
- Rules –> Readability Rules –> Regions –> Check SA1124. For the love of a higher deity, please stop using regions. If you need regions, your code is tackling too much.
That’s quite a bit to configure, but seriously makes your code at least consistent. Not only for yourself, but for your team.
Side Note: For those that use StyleCop, you’ll notice that this means that SA1101: PrefixLocalCallsWithThis. Yes, this is intentional because it does improve readability when I’m looking at the code outside of an IDE. Is the line BuildDetails.Name an instance property digging into the Name property, a static property digging in, and static class, or what? By saying this.BuildDetails.Name it is now much more obvious where I need to look for that code.
