Comment should not include code

Posted on Oct 18, 2015 by Morten Empeño

In the last few year I have been working as a Tech Lead, with the focus and the responsibility of code quality. Something which I see again and again, in the teams and the projects I am related to, is code being commented out, and still being checked in to our revision control. I guess the main idea of having commented code, is: Hey... I am trying something here, and I am not quite sure, if I should use this commented code at a later point.

It is a Code Smell

I have had several discussions on the topic, with several developers. Most of them argue, that code which is commented out is harmless. Their facial expressions even - from time to time - tell me, what an idiot I am, bringing up this irrelevant topic. But I am right:). At least I think, I am right - and why is that?
Here are the most important reasons on why I think commented code is a code smell:

Uncommented code normally raises more questions than it gives answers. It may seemed very smart, when the developer was in the context of a specific piece of work, but a few months later, it can be quite difficult the get the idea. And hey.. if a code being commented out was even necessary, doesn't it tell that the developer did not finish the work completely? I guess it does in some situations. At least it can be very time consuming to understand why code was commented out in the first place - sometimes even impossible.
Maybe only one person knows the reason for the commented code. An this person will probably forget very quickly why the commented code is relevant.

Commented code is a distraction when reading code. The commented code simply disturbs the flow of eyes.

If some code must be conditionally compiled, there is a way to do that. You should use it. That is why it is there: :)

#if DEBUG
  Console.WriteLine("This piece of code is only hit, when in debug mode!");
#endif

And you should clean up the if statement, when you have finished playing around, and when you have found the answer for what you were looking for

"But, I just want to have the piece of code in there for a little longer, as I......"
"NO NO NO - Clean it up"
"But..."
"NO"

Code should be clean. If you do not agree, please take the discussion with Uncle Bob, before you take the discussion with me. He will eat you, I am sure :)
But did I never check in commented code myself? Well, that is a different story :)

Back to List