Using differentials to move the team in the right direction

by g. ann campbell|

    In my last post I talked about differentials, which are my favorite feature in SonarQube. I could have - perhaps should have - talked about the philosophy behind them, but I didn't want to muddy the waters. So this time it's about philosophy.

    Why are differentials important? A lot of people will tell you that you can't know where you're going unless you know where you've been, and differentials can certainly help you see that. Others will tell you to put the past behind you and focus on the present. In a way, differentials let you do both of those things.

    One of the foundational principles we push with SonarQube is that you shouldn't start mopping the floor before you've plugged the leak. For instance, you shouldn't worry about cleaning up old violations until you've stopped adding new ones. You shouldn't worry about catching up missing test coverage on old code until you've stopped checking in uncovered new code. And so on.

    That's why the first default differential period is Δ since previous analysis. If you're using Continuous Inspection, and analyzing on a daily basis (conditional on there being code changes) then this first differential lets you focus on how you did yesterday. Because it's not important at first that you've inherited an enormous technical debt on a legacy project. What is important is that the team begins to develop better, healthier habits.

    If you're reading this, then you probably already know that it's not enough to install SonarQube and set up analyses. Someone has to look at the results. If you're in this initial, "developing healthier habits" period, then someone - preferably everyone on the team - needs to look at the results every day (thus developing another healthy habit ;-). Because you need to raise awareness that it's not okay to keep violating the coding rules and standards that the team agreed to, and a little healthy peer pressure here can go a long way.

    As someone who cut her teeth on C, I personally prefer to leave curly braces off of one-liners, E.G.

    if (aBool)

    I think it's cleaner. Plus you can fit more code in a screenful! But the rule requiring them is one the rest of my team likes, and we've all agreed to follow the same standards.

    The fact is that in a group with a mixed set of habits and expectations about code formatting, leaving curlys off leaves the door open to bugs. So now I use curly braces - even though I know that those two extra keystrokes will add up to hours over the course of my life! :-)

    Of course, I wasn't rigorous about it at first. But seeing my id next to the new violations (courtesy of the SCM Activity plugin) was embarrassing, so I cleaned up my act, and eventually, we cleaned up our code. But the first step was plugging the leak.

    Code coverage is another example. At my day job we have legacy projects. Lots of them. With lots and lots of lines of code. And no tests. The thought of catching all that crusty old code up with tests... well, it's not pleasant. Fortunately, with differentials you can focus on making sure you don't perpetuate the problem. The On new code feature in the test coverage widget lets you see the coverage on changed or added code, in isolation from what hasn't been touched in the differential period. So it doesn't feel like you have to tackle the mountain of uncovered code to make a dent in the coverage question. You only have to "go forth, and sin no more."

    Of course, there are always wobbles. Some days quality is down a little, with maybe a leap the next week. The "previous analysis" differential is useful to keep yourself on track, but it's also nice to be able to look a little longer term. There are three global differential periods, but for each project, you can also set two additional differentials. For the global differentials, time periods are most useful: 5 days, 30 days, and so on, but you can also set differentials against specific dates. Or versions.

    Each time you release a new version

    I said at the beginning of this post that differentials will let you focus on either the present (Δ since previous analysis) or the past. Whenever the team at my day job sets a new benchmark, I re-set the third differential period to that date. That makes it easy to see how far we've come since the benchmark, which is worth looking at occasionally.

    By default, SonarQube shows you were you are right now, which can be disheartening on a legacy project. We started our SonarQube journey with reams of legacy code. I.e. a staggering technical debt. Sometimes it feels like trying to empty the ocean with a teaspoon. That's why differentials at the long-term end of the spectrum are important too - because we are making progress, even with a teaspoon. Lose sight of that, and it could be easy to give up.

    But it doesn't matter how big your technical debt is. Like credit card debt, it only matters that you've stopped running it up and started paying it down.