Sunday, March 20, 2016

Is your codebase smelly? Find out with the help of SonarQube and the Smells plugin!

In the project which I recently joined, I discovered a set of annotations, (part of the code) that eventually did not add any functionality but they were 'marking' classes or fields  as a potential bad implementation, or as a potential case that may need to be reworked. The original author, had created a very elegant way (imho) on annotating parts of the code, for things that needed to change or to be improved. This mechanism was mostly targeting less senior contributors so they improve and at the same time, it was marking 'smells' in the code that unfortunately were not a 5 minute fix and might need a bigger change or discussion around it.

@TechBebt ("rework this method, so that takes care this business concern")
@Refactor ("Use the proper data structure for this operation, see LinkedList");
public void doSomething(String aParam){

In the past I used to work in projects where this kind of code-review and comment process was performed using our famous following comments. You might have some of those in your project I guess.

// TODO 

I really liked the annotation approach, so since I am new, I started searching for them all over the place. When I found something that I could fix, I followed the annotation's description field, and I could provide a small bug fix. It seemed to be a bit cleaner than the long sentenced TODO items. The problem with the above annotations is you will bump into them, only if you happen to see them, or search for them in your IDE, where TODO or FIX-ME usually show up in IntelliJ's or Eclipse's task (todo) list.

At the same time, I proposed to install Sonar for the team and eventually monitor the 'health' of our code base improving the exposure of this information to a wider audience. The more you expose your code problems to the team, the easier you make this information to anyone, the more chances you have members to contribute fixes rather than dictating it as a process.

While I was configuring Sonar, I discovered the Qualinsight Smells Plugin, along with their maven library. Eventually it is a library that contains similar annotations to those I discovered in the project, so you can add it as a dependency in your project and start 'marking the smells'. These annotations then can be scanned by the related Sonar Plugin, so when you code base is scanned, in the final Sonar report, you can have a list of  all the annotated 'Smells'. You can go through the simple documentation on github. A smell annotation looks like this: 

@Smell(minutes=10,reason="This class should be redesigned in order to", 

You have to indicated
  • an estimate of time for a potential fix.
  • the reason, actually the description of the smell.
  • and a set of predefined types, in order to specify what kind of smell it is. The provided list is  sufficient enough to cover most of the cases.
You can find an example of project configuration here.

When the Sonar report is ready, the smells are going to be listed , as the image below illustrates.

I really liked the overall approach. Despite the fact that our ultimate goal is eventually to fix the code and only 'annotating' defects, I still think it is a very elegant idea. Especially when your team consists of less senior developers or 'devs' that they don't pay attention to things like quality and maintainability of the code base, it is a very 'constructive' and elegant way to bring forward these concerns and with the help Sonar, increase their exposure. It is also a team effort, identified Smells are not predefined rules from findbugs or PMD, they are human identified  points, there might cases where the code is fine, but it does not implement correctly the business.  Sonar enables non technical stuff to eventually have access to the 'state' of the project, so yet another way the product owners/ managers to a better understand about 'technical debt'. your code base smelly? If yes do something about it. Nobody likes smelly code.

ps) All credits to M.Pawlak  (@QualInsight) for his work on this library.


  1. Thx Paris nice article, I think though that if a developer doesn't have the dedication to write an explanatory todo or fixme the annotation will be more trouble for him....

    1. The annotation is just the same todo / FIX me comment. it is just now parseble by Sonar and you can have a nice overview of them

  2. Hi, I'm the author of the Smells plugin and wanted to provide some details about the plugin and the way it should be used.

    While FIXME / TODO comments are written by the developer having written the code, the @Smell annotation is meant to be added by his/her colleagues, fellow developers. Thus the main difference here is that the goal of @Smell is to inform a developer and a team that something needs to be discussed and probably fixed.

    A typical @Smell usage usecase is when you're reviewing code and/or are adding a new feature and you find a Smell that needs to be fixed. If you have the time to fix it maybe you'll do it right away, however there are numerous situations where it's not possible (due to deadlines) or where it's preferable to inform team members of the issue.

    For instance, it's better to inform junior developers that they have done a mistake and then let them improve their code (clean you own mess or you'll keep doing the same mistakes). When working in an agile fashion, you can discuss smells with your team during your next sprint planning and decide how each smell should be tackled / added to your roadmap (severity and remediation cost evaluation are meant to help you in your agile process.)

    You may argue that there are tools made to help you in your code review process (gerrit, crucible) or even some that enforce the review (GitHub, BitBucket, GitLab pull/merge requests). However, all these tools require a specific installation (or even license) and none integrates with SonarQube as the Smells plugin does.

    By the way, @Paris your screenshot is incomplete (IMHO Google Visualisation API is unreachable from your browser. The widget should display a nice donut graph next to the text. You can see it on the plugin's page:



    1. Hello, thank u for your comment. Apologies,for some reason it had been marked as spam.