We all have old code snippets in our code base. Whether it’s a method that’s no longer used, or a few lines that we’ve replaced - our code has sections commented out. When should we remove them? How should we comment them out? If you’re not careful, commented out code can cause future problems. Read on.
Code Gaffe #1: Sneaky Commented out code
Commented out code should be, well, really commented out.
Really comment it out
Don't put a /* at the top and */ at the bottom of code you want to remove:
/*
code block line 1
code block line 2
*/
Why? If the code block is of any size, someone reading the file may not realize that the code is commented out. And you're simply causing them to waste time. Instead, comment out each line:
//
// code block line 1
// code block line 2
//
Of course, in modern editors with syntax coloring, this should not be an issue because the commented out code will be colorized as a comment. But we don't all have color printers, and sometimes we still use printouts. And we use other tools besides editors (like file differencing tools, change reports, etc.) that don't have syntax smarts.
Besides, if you have a modern editor (and even with some ancient ones), you can select the code block to comment out, press a key, and it'll add "//" to every line - so there's really no excuse to not do it this way.
I knew a guy who was very puzzled while trying to fix code in an overloaded method that he didn't realize was commented out. Due to the nature of the code, he couldn't use a debugger, he had to dump info to a log file for debugging (and he didn't have syntax coloring). After wasting a day doing this, he finally saw the comment markers on an early page, and with appropriate *&^*% language, found the correct overload.
CodeGaffe #2: Old Commented out Code
The real reason we can't bear to delete old code is that we spent so much time writing the code in the first place
Of course, the best tack by far is to delete the unused code. The code will rot when it's unused, and after a while, you wouldn't be able to simply uncomment it anyway. If you really can't bear to delete it, make it obvious that it's commented out.
What do I mean by "rot"? Once the code is commented out, it's never getting executed. As the rest of the code base evolves (adding new features, fixing bugs, refactoring), the code will be out of date—perhaps very subtly.
Delete the old code (I know, it’s hard to part with it )
The rule of thumb I use is to comment out code if I think I might need it again very soon. Then, the very next time I'm in the same module, I delete it. Thanks to the wonders of source control systems, it's now very easy to see that I intended to remove the code, since it'll be commented out in one version and gone in the next. That's a little more obvious than simply removing it.
This suggestion (comment then delete) is really for those of us who hate to delete the code outright, "because I might want it back someday". Usually though, the real reason we can't bear to part with it is that we spent a lot of time writing the code in the first place. But my advice is to delete it once it's no longer used.
So clean up that old code. Get to it!
Technorati tags:
CodeGaffes,
Geekswithblogs