Eradicate Commented-out Code From Java Applications

There have been numerous debates around commented-out lines of code (line or block of code that was commented out at some point) and whether they should be left in the code or taken out. The outcome of those debates is almost systematically that they should be taken out sooner rather than later : in the Sonar Team, we generally consider than later means after code check in.

Here are the main reasons why old commented-out code is an abomination :

• It always raises more questions than it gives answers
• Everybody will forget very quickly how relevant the commented code is
• This is distraction when going down the code as it stops the flow of eyes
• It is a bad SCM engine : Subversion, CVS and Git are really more trustworthy !
• The simple fact of understanding why code was commented out in the first place can take a lot of time

But the worst of all is in my opinion the fact that commented-out code appeals commented-out code, similarly to The Broken Windows Syndrome ! All this was reinforced by Uncle Bob a few months back in his Clean Code Tip of the Week #7.

There are less discussions about how to tackle this. At least, common sense rules can help to overcome the fear of suppressing such commented-out code :

• Rule 0: Commenting out code is ok, commiting commented-out code is not
• Rule 1: Don’t check in modules that have commented-code
• Rule 2: If you check out a module that has commented-code, delete that code

This pragmatic approach is fine and when adopted the number of commented LOCs is going to decrease throughout time as long as everybody in the team respects the rules. But how to make sure it is the case ? How to measure the current level of commented-out code ? And what’s about the dispersion occurring every time a developer hits some of it ?

Sonar in its version 1.11 has become the ultimate tool to measure and hunt down the commented-out code in the same way it is used to track down potential bugs, complex methods, untested code, duplicated code…

The hunt can start on the project dashboard where the total number of commented-out lines of code is displayed in the “Comments” widget.



When you click on this indicator enables a drill down from project to source code to view the lines of dead code.

To develop this functionality, we have put in place a pretty simple pattern recognition engine that finds commented-out LOCs. For Java language, there are 5 patterns and every time a comment line matches one of those, the probability it used to be a LOC increases. Once a threshold is reached, the comment line is flagged as a commented-out LOC and reported as such in Sonar.

Uncle Bob, if you read this article here is a special message for you : “Clean Code” is really considered as a bible within the Sonar team, and it has directly inspired this new feature. You should have a look in Fitness as there currently are 46 commented-out LOCs in the project :-)