StyleCop for .Net 5 Projects: Clean-up

With your StyleCop installation done and your custom configuration in place, you are now ready to clean-up your project. This is part three of my small series of StyleCop for .Net 5 Projects:

• Part 1: StyleCop for .Net 5 Projects: Installation
• Part 2: StyleCop for .Net 5 Projects: Custom Configuration
• Part 3: StyleCop for .Net 5 Projects: Clean-up

 

First reaction: WHY are we doing this again?

A newly created project with the default template may already create 20 StyleCop warnings. It is therefore no surprise that long-running projects end up with tens of thousands of warnings. Before you run away, remember why you are doing this clean-up.

If you are beyond 10 000 warnings you already feel the pain: every class looks slightly different, every code-review ends up in an endless nitpicking session of style and formatting while there is never time to address the other aspects (like security or quality). If you want to get away form that place you need an agreed-upon set of rules and you must check them automatically – otherwise you end up at the same places as you did the last few times you tried to follow a set of rules. That automatic checking is what StyleCop does, but to keep your code free of warnings you must first fix them.

 

Cleaning-up is a whole team activity

The new rules you want to follow need the commitment of everyone on the team. It does not work if some people obey those rules and the others keep writing code as they seem fit. The sooner everyone follows the new rules, the faster your code improves.

The initial clean-up is a boring activity. Fixing the StyleCop warnings will therefore go down as all other boring task, i.e. the same few developers will clean up while the others are busy creating more features (or more likely, a bigger mess).

If you want to create a change in your code, you must create a change in your team. Make sure that everyone does their fair share of clean-up and you are not only done much faster, but everyone understands that they are in this together.

 

Keep your code free of warnings

Let us jump one step ahead and look how we are going to keep our projects free from StyleCop warnings. In my experience there is only one way to do that: we need the compiler to help us and break the build as soon as a warning pops up.

In Visual Studio we can go to the project properties, open the build tab and select “all” in the section “Treat warnings as errors“:

You need to set this option for all your projects. As soon as you do that, every warning, independent of the source, will break your build and the developer is forced to fix it immediately. You cannot get a faster feedback cycle than that.

But before you can activate this safety net, you must fix your warnings – otherwise you cannot compile your application.

 

Strategies that work to address StyleCop warnings

Depending on the numbers of warnings, the timeframe to clean-up your project and how intense you are developing your application, you need a different approach to get rid of the warnings.

 

Fix warnings as part of your work

The simplest (but most likely longest) way to fix all warnings is to extend your definition of done to include that every changed file must be free of warnings. This approach will improve the most heavily developed parts in no time, while the other parts of your application may contain warnings for a while.

If you pick this strategy I strongly suggest you make separate commits for the clean-up and the feature related changes. Otherwise you will have a hard time to do code reviews.

 

Fix warnings by Project

If you need faster results, go through the list of our projects and use the Round Robin method to assign them to your team members. Then take a day of your next iteration in which everyone fixes the warnings in their assigned projects. As soon as all warnings in a project are gone, activate the “Treat all warnings as errors” option and go to the next project. If there are too much warnings to fix them in one go, repeat those clean-up days in every iteration until all warnings are gone.

This is my favourite approach, then even with an enormous amount of warnings you can make a steady progress and create small islands of cleaned-up code. With the compiler checks in place, those islands stay free of warnings even when it takes months to clean-up the whole solution.

 

Fix warnings by StyleCop rule

As you did when deciding what rules to keep you can compile your solution, order the warnings in the Error List window by code and use the round robin method to assign work to the team. Some rules have significantly more warnings than others, but with enough broken rules it may level out. Should this not be the case, you can swap a few rules between team members until everyone agrees that this is a fair distribution.

This approach needs a lot of coordination because you potentially change the same files at the same time. You can prevent this with tiny commits containing only one file or by using time slots you assign to the team members (you clean-up on Monday morning, you take Monday afternoon, and so on). Nevertheless, this is my least favourite strategy because it is so easy to make an even bigger mess.

 

What did not work so well to address StyleCop warnings

Over the last 12 years I had many opportunities to use StyleCop in various teams. Not every idea we tried worked out well. While your team may be different, I advise against these approaches:

 

High-water mark

You can count the warnings you have in your solution today and decide that at the end of the next iteration you want to be 10% lower. You repeat this until you are at such a low level that you aim for 0 warnings. That seems to be a simple approach, but it has its problems.

First and foremost, it is easy to let the others do the boring work of cleaning-up. This means that the developers who care about improving the code end up doing all the work. Even worse, if only a few developers work on reducing the numbers, the others may create even more warnings. That leads to the point that those who clean-up not only have to fix 10% of the warnings in an iteration, but maybe 15% or 20%. It does only take a few iterations until they stop cleaning-up and follow the tolerated example of the others. Before you know it, you have many more warnings as at the beginning, but no one left to improve the situation.

 

Let everyone take their own pace to clean-up

This may sound great in a self-organising team and probably even works if you have enough mature developers. More likely is that you combine the negative effect of the high-water mark with the lack of accountability to improve your code base. Those who clean-up the code will quickly stop when they see that the others create an even bigger mess.

 

Using ReSharper to clean-up

At the time of writing this post in March 2021 there is no support for StyleCop in ReSharper. That means you need to manually change the configuration of ReSharper to create code that obeys your StyleCop rules. This extra work needs to be repeated whenever ReSharper or your StyleCop rules change.

In the best case you get a head-start with the auto clean-up feature of ReSharper and save yourself hours of manual work. In the worst case you spend more time to figure out where ReSharper changed something it should not have.

Therefore, be aware of potential problems and the extra work of keeping two different rulesets in sync before you decide to use ReSharper. It may still be worth the time, but it will probably be significantly more work than you expect.

 

Parting thoughts

After the hard work of getting rid of all warnings your code is in a better state. When you put the “Treat all warnings as errors” option in place it may even stay that way without much additional effort. That is the directly visible effect of StyleCop that everyone will notice who works with your code base.

For me there is an even more significant change in place: The automatic code check makes the manual, nitpicking one at code reviews obsolete. That gives you the opportunity to look at the important parts and learn as a team. New team members do not need to debate code style and what they prefer, they just can write code, listen to StyleCop and fix what is not following the agreed-upon definition. Again, an invaluable time-saver that helps you to focus on your application. Try it, it may put an end to many of the endless discussions in your team as well.