Mark Needham

Thoughts on Software Development

The danger of commenting out code

with 19 comments

An idea which is considered common sense by most developers but which is not always adhered to is that of not commenting out code.

Code is nearly always under source control anyway so commenting out code which is not being used doesn’t really serve any positive purpose and it can have quite a few negative effects.

Clutter

Ideally we should be able to read through the code without too much confusion – each method’s name being descriptive enough that we can work out what is going on.

Having commented out code stops the flow of your eyes as you go down the code – there is a distraction and you want to know what it is.

Even more time is then wasted trying to work out why the code was commented out and whether it might still be useful or not.

Misleading

Unless we trawl through the source control history it is difficult to know when and why a piece of code was commented out.

Sometimes when we discover a bug in our code we eventually end up debugging an area of the code which has some code commented out.

If that bug didn’t previously exist then the natural thought is that perhaps commenting out that code is what caused the bug to appear. Clearly that is not always the case!

I have debugged code before which had parts commented out where uncommenting the code actually made the situation even worse.

Leaving uncommented code in seems fairly harmless but it can waste quite a bit of time if someone misunderstands why it was commented out in the first place.

Broken Window Theory

The Broken Window Theory proposes the idea that if we do one bad thing in our code (i.e. break a window) then it becomes more likely that the next person who encounters that code will do something bad as well eventually leading to the degeneration of the code.

This is the same when commenting out code – if people see that there is code commented out then it becomes more acceptable for them to also comment out code and before you know it there are large chunks of code commented out and noone really knows why.

So is commenting ever ok…

I think commenting in the sense I describe here only really makes sense in the short term i.e. commenting out some code to see whether it is actually needed or not, running the tests, and then deleting it permanently if necessary.

If our aim is to produce expressive and easy to understand code then removing code when it is no longer needed can go a long way to helping us achieve this.

Be Sociable, Share!

Written by Mark Needham

January 17th, 2009 at 4:02 pm

Posted in Coding

Tagged with

  • Pingback: Dew Drop – January 17, 2009 | Alvin Ashcraft's Morning Dew

  • http://betarelease.blogspot.com Sudhindra Rao

    Hi Mark,
    Actually commenting out code is never ok NEVER. You can just delete that code and run tests. If your tests fail just do an svn revert..

    Commenting out code in development often leads to commented code in version control and you have a broken window right away.

    -Sudhindra

  • Pingback: Reflective Perspective - Chris Alcock » The Morning Brew #267

  • http://www.netpmg.com Dan Swatik

    Well I know from past experience (past jobs) that we always left code we commented out to refer to later just in case a bug arises with the newly revised code…and it has saved us a lot of time and work down the road.

    So in my humble opinion commenting out code and leaving it around for a spell or two isn’t a bad thing… its just a matter of opinion and what you choose to do with your code.

  • http://www.cybergroup.com Douglas Phillips

    I’ve always made a point of including a note as to why, when, and who commented out the code. It adds a couple of lines but makes it much better down the road.

    On the other hand, I *HATE* commented code with only a set of initials and *maybe* a date…

  • http://gleichmann.wordpress.com/ Mario Gleichmann

    As Uncle Bob pointed out within his Book ‘Clean Code’, you better use your version control system for tracking code history (as it prevents another problem with commented out code in my opinion: you never know in which chronological order your code was commented out, so you never know if two or more commented out code blocks relate to each other or not).

    Greetings

    Mario

  • SandFlyer

    Another reason for deleting commented code: when you make a site-wide search of a keyword and get all these supposed “matches” which are really commented out code.
    I’ve had to wade through screens and screens of commented out code, and I think that using version control correctly is a much more elegant solution.

  • http://www.hieu.co.uk HieuUk

    As my experience when I worked on other people’s project, they left me a few million lines of codes and some random comment out code which I bet they don’t even remember what it’s all about after a few day. You don’t know what it’s about, you don’t want to delete it because it maybe important, who know!
    I think after test we should delete all the temporary comment out code. But leave some comment out code isn’t too bad if you mark down some explain what the code all about.

  • http://shifteleven.com K. Adam Christensen

    Another reason, and for me, this is the most important: This can mess up merges.

    I’ve run into merges where commented blocks get intertwined with functional blocks and it’s just a mess. It could even be something as innocuous as reformatting the commented blocks that end up causing a lot of unwanted pain.

  • http://gen5.info/q/ Paul A Houle

    Hell yeah.

    I worked with a team that loved to comment out code. Some source files were 80% commented code and 20% working code. This hurt readability a lot!

  • Pingback: Agile: What is it? at Mark Needham

  • http://intwoplacesatonce.com Dave Cameron

    A few people are referring to this, but I think it’s worth calling out explicitly: commenting out code undermines the team’s confidence in the code. It is close to an outright admission of “we don’t understand how the system works, we don’t understand how to fix it, we’re just trying things and hoping it starts working better.” That’s not a great situation to be in.

    Even if that is close to reality, it’s better to start building confidence by making deliberate changes. If the change is wrong, that’s okay, and use version control to revert it.

    Don’t be so afraid of making a mistake though, that old code is just buried further and further under comments in some sort of code-based landfill.

  • Mike

    Finally, I thougth I was the only one that hated commented codes, the distraction, I cant stand it.

    if you use good descriptions of you’re functions, objects and variables, and space out you’re code reasonnably, comments are useless.

    But I also hate when they short name something, as dt for a datatable. Something like dtCarMakes keeps it simple, clear, and commenting it would d be useless.

  • http://www.markhneedham.com Mark Needham

    Possibly even more nightmareish is when abbreviations on variable names no longer matches the class name because the class name has changed and the variable name hasn’t. Then the code is truly confusing.

    There’s a really good section in Code Complete about how we should name thhings in our code. I think I need to read it again from time to time to remind myself.

  • Pingback: Refactoring: Removing duplication more safely at Mark Needham

  • Pingback: Coding: Unused code at Mark Needham

  • http://www.tiendq.com Tiendq

    From my experiences developers often make long commenting out code for reference later, and they often forget to remove it when it is unnecessary too. It makes messy code. If you just want to do a quick test, feel free to comment code but please don’t commit to code repository. It is likely that only you who know why the code is commented out.

  • Stephen McMahon

    It is my opinion that commenting out code is discourteous to other developers. Nothing to me is more frustrating than being assigned to find a bug in another developer’s code only to find that the file is loaded with dead code. I’m dealing with a c# source file now for which not only is about 80% of it commented out, many of the commented out sections are surrounded with things like “#region Commented out” No joke.

  • Rich Wandell

    An excellent article that echo’s my thoughts exactly! I have worked in situations where I have encountered large (100+ lines) amounts of commented code and every encounter leaves me wondering how the developer of this code could work under these conditions. I find commented code to be a distraction and also a discourteous gesture towards your development team.