Commented code is a code smell

Imagine going into a friend’s office just to grab an instruction manual. Now imagine that as you open the door you get a strong smell of dry parchment. With the door open you discover a vast mound of manuals. You just want to get a manual but you want to grab the most recent instruction manual.

So, you start digging. As you sift through the manuals you discover that most of the manuals are old and even contain lot of crossed out text. In other words the old outdated manuals themselves contain outdated parts within. It’s time to abandon hope. You leave your colleague’s office to go back to yours. And you send him or her an email to please send you the most recent instruction manual. It ends up taking a week but you finally get the most recent instruction manual. And as you pop it open you discover that 30-40% of the manual is crossed out as no longer relevant to the manual.

Finally, you abandon hope.

The story above is my experience when I go visit some code projects. As I pry open files and start trying to reason about the program’s inner machinations I discover paragraph after paragraph of commented out or irrelevant code. Alright maybe I’m exaggerating the quantities here but the harm against code readability is real. I would argue that commented code should be considered a code smell.

The underlying reasoning for keeping old commented code around seems to be that even though we’ve moved away from using a piece of code we should comment it out for safe keeping in case we might need it later. But that’s what we have version control for!

Use comments for explaining code as it currently is. Never let old comments stick around. Irrelevant/wrong comments are downright unhealthy for a project. Though you might consider commenting out code that is soon to be activated. But that’s a big, fat “it depends”.

When in doubt eliminate the offending commented out code. Let the version control system remember it for you. Most likely you won’t need it. And future coders will thank you when they’re not forced to wade through a quagmire of stale, unused, commented out code.

There’s always that sting of throwing out code that you’ve poured blood and sweat into writing. It wasn’t super easy for me to start liberally removing code. But I quickly got the hang of it. And it greatly improved the experience of revisiting code written by me after long periods of working on other code bases.