Commented Code == Technical Debt

Over the last month I have spent countless hours modifying code in our
development framework. This framework is nearing the 4th grade now (9
years old) and has had many sections modified or rewritten extensively
over the ensuing decade.

A common technique I used when changing code was to comment large swaths
of code and insert new code in its place. I can tell you now this
technique was a poor idea and has wasted a considerable amount of my
time. This may sound obvious to you but to some it might not. Here’s
what I experienced:

1) Every time  found a commented block I was forced to perform a context
switch. Why did I comment this code? These context switches are the
equivalent of a phone call or a child coming into the home office to
play. It takes precious time away from the task at hand.

2) The commented out code takes up space on the screen and in the flow
of the code. This requires a mental filter and a minor context switch.

3) And finally it is like doing testing after the fact. If you find
yourself adding comments to your code: //REMOVE THIS CODE LATER you have
lost. Just kill the code now. You wont remember why you added that line
in the first place so just don’t do it. kill -9 that cruft now.

So what if you feel like your code is precious and needs to be kept
intact like it’s the Magna Carta? Just use your version control system.
The code will always be there to recover like the the Ark of the
Covenant. If you don’t have a version control system get one. There is
NO reason not to.

So now that I have your attention… kill that cruft. Otherwise I’ll submit your name to my new reality show: Code Hoarders

NOTE: For those of you that are code comment haters, this post is not
for you. Relevant comments are always a good ideas and should be used.
 Consider this flame bait if you so desire :)

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • Source control solved this problem long ago. :) The only time you see old code is when you want to see it.

  • Agreed nathan. I am master of the obvious but sometimes us old dogs need a reminder:)

  • Rob

    Totally agree. The worst scenario is when you’re not sure if the commented out code was done accidentally. Should you uncomment it, or leave it commented out. Why did they comment it out and not remove it? Such a time wasting exercise.

    I strip it out straight away. That and any comments that don’t make sense, or are simply things like “WARNING”.

  • Ole K

    Reminders of the obvious is what makes us remember them ;)

    I can only quote Uncle Bob from one of my favourite books (Clean Code): “as soon as I see commented out code, I delete it straight away without even looking at it” (or something in that direction).

  • I agree but, anyone knows what command lets me find old code that I removed (instead of commenting out) using TFS or SVN? (No, history/log doesn’t count)

  • “I see dead code.” Man that sounds scary!

  • Returns true. You probably meant it to be a single equals, otherwise, this post is a question. :)

    Well written code shouldn’t need comments.

    If you use comments to explain the flow, you obviously need to look at refactoring.

  • Couldn’t agree more. I’m definitely guilty of commenting out code and not getting around to actually removing it. Gotta work on that.

  • You are not alone Rod. I have seen this in lots of Legacy Code I maintain – so much so that I consider it code smell and a sign of trouble!!

  • Boohoo cry me a river. You must be a real snob if you feel smug about deleting commented out code that some one else probably needed but just didn’t know how to put code based context switching (IE debug mode vs production mode) in their code.

    How much technical debt is it to simply ignore the comments like the compiler has.

  • Amen, bro. I’ve blogged about that a little while ago, too:

  • Tudor

    To me such attitude just seem arrogant – indeed in many cases commented code can be just deleted and TFS/SVN use instead for looking into history – but in real and not-so-ideal world, in many cases, somebody has to modify (or comment out) several pieces of code and he has to make sure he write down _why_ he did this, so anybody working later on that piece of code knows _why_ that change was done – in real world, very few people document all code changes in the check-in comments (and it would be impractical to do so for hundred of changes).

    So in a less-than ideal world, where not all code is self-describing and crystal clear, commented code with clear comments explaining _why_ the change is necessary, are a must, unfortunately.

  • @tudor: why is it impractical to document code changes in check-in comments? perhaps you check in to seldom? And if in your real world, people don’t document code changes, why treat the symptom (using commented code blocks with explanations in the source files) instead of curing the disease causing the symptom? (smaller check-ins and proper commens on all checkins).

    There’s no must here, only bad practices.

  • Tim

    “For those of you that are code comment haters, this post is not for you. ”

    Why would a “comment hater” object to your deleting comments? I think you would instead make friends over a post like this!