Differentials: but wait, there's more!

by g. ann campbell|

    In my last two posts I talked about differentials. First, it was the four ways they show you what's changed in your code from "then" to now, and then why the ability to see those changes is important.

    You'd think I'd be done. There's no more left to say about differentials, right? Wrong. If this were an infomercial, it would be now that I'd say "but wait, there's more!" This time I'll talk about the last few pieces of the differentials story I haven't told you yet: alerts; filter values; extra differential periods; and version differentials, and about how to use them effectively.


    I'll start with alerts, which are simple, boolean thresholds you can set on a rule profile. Whenever a project is analyzed with that profile, if one of its metrics crosses the threshold, an "alert" is raised on the project. Raising that alert takes a couple of forms. If you've signed up for alert notification (either globally or on specific projects), you'll receive an email.

    You'll also see the alert metric "light up" with color on dashboards: orange for warning alerts and red for errors.

    So what does this have to do with differentials? Well nothing, if you're talking about standard alerts, like "Blocker issues > 0". But alerts don't have to be on exact numbers. Let's say you're applying the same rule profile to your greenfields projects and your legacy projects (which is the right thing to do). Setting an alert on Blockers > 0 could mean that there's always an alert on some of your legacy projects. Like the boy who cried wolf, you know that an alert that's raised for every single analysis will soon be ignored. But you can set alerts on differentials!

    Instead of setting that alert on Blockers > 0, you can set it on the change in value versus any one of the three global differential periods. So you can limit your alerts to only be raised when when the number of Blockers increases. That way you're holding everyone to the same standard - no new blockers - without hammering the teams that inherited their blockers along with their legacy projects.

    Filter values

    The next thing you can do with differentials is display them in filters. At my day job I have a "Delta" dashboard that shows a filter holding every project analyzed in the last week. Instead of showing the standard Issue counts and LOCs columns, this one has differential columns like: LOCs Δ last, New Issues Δ last, Issues Δ last. Now we can see at a glance how multiple projects are doing. I picked "since last analysis" differentials for my Delta filter, but you can show the change against any of the three global periods. Depending on your situation, it may be more helpful to show the differential versus a longer period, but I'm usually looking to see who added violations over night. Before teams get used to checking their own work (either in Eclipse or directly in SonarQube) it can be useful to offer a nudge when you see the numbers headed in the wrong direction.

    You may be wondering why I include both Issues Δ last and New Issues Δ last. That wasn't a typo. I use them both because they're not the same. The Issues Δ will be a net change. The New Issues column will show everything that was added. As you can see, those numbers don't always match up.

    Extra differential periods

    You may have noticed that I keep referring to the three global differential periods. That's because there is a distinction to make. In addition to setting three differential periods that will be applied to every project in your SonarQube instance, you can also set an additional two differential periods per project.

    So if a project hit a significant milestone on a given date - let's say you finally got that last development opening filled, and the new guy started on the first of the month - you can set an extra differential on just the one project to measure that extra progress you've been promising the bean counters you'd get with a full compliment of developers.

    Version differentials

    But you don't have to tie your project-level differentials - or any of them for that matter - to dates. I've talked before about setting a differential period to the Δ since previous analysis (set with previous_analysis), and clearly that's not a date. Well, it's not the only non-date option.

    Version increments are significant project milestones, and SonarQube recognizes that by letting you tie differentials to them. You can compare to the last analysis, and Δ since previous version (previous_version) is also available. It makes a great candidate for one of global differentials spots. You can also use specific version numbers, but I'd save them for a project-level differentials.

    Why would you want to measure your current state versus a different version? SonarSource CEO Olivier Gaudin gives three good reasons:

    "If you think about it, the software that you really have to maintain is the one that is shipped to production. Indeed, this is the one that has bugs that need to be fixed, this is the one end user interacts with... This is therefore the one you want to make sure you will not degrade."

    Plus, there's the fact that you want to leave room for a little creative chaos. After all, you have to break a few eggs to make an omelette, and in the course of writing new code, you may introduce a few new issues that you can't fix immediately. "So, you will always need to refer to the previous version to see exactly where you stand technical debt-wise.

    "Finally, the final guardian - the release manager or someone like that - will check this differential (before a release) and therefore this should be your reference as a coder."

    So there it is, the full scoop in differentials. They let you see what's changed - from the macro to the micro level. They alert you to problems. They help you stay on track. Is it any wonder they're my favorite feature in SonarQube?