It’s surprising how small steps and habits can do so much to improve the quality of our code. By quality, we also mean readability—how easy it is to understand a piece of code by reading it, much like a short story. I always say that if you can understand what a piece of code does in one or two passes, it is probably well written.
So what are those commented-out chunks of code doing there when, logically, they will never run?
This is one of the bad habits we need to break. Leaving traces of obsolete code gets in the way of making code readable and easy to understand.
Anyone who takes over your work and comes across it will first wonder: Is this a fixed bug? Was it left there for some reason? Is it important? These interruptions while reading code distract from the rest and create doubt.
The reason we tend to leave commented-out code is obvious: it’s hard to delete work we’ve already done. But precisely that process of tearing down (removing something that isn’t right) and rebuilding (re-creating it to make it better) is what improves our software. So why leave traces of what came before? Another reason is that sometimes we hesitate and aren’t sure about the changes we want to make. That is easy to resolve: a good suite of tests should tell us whether our changes are sound.
Besides, what is source control for? If we change something and delete a block, we can always recover it later, as long as we manage our source control system properly.
This isn’t a call for extremism. Software development has a playful side, and we shouldn’t rigidly adhere to every rule, practice, and good habit we know is necessary to do good work. My point is that production software that must be maintained and reviewed should not contain blocks of dead code.
“Let’s not leave commented-out code behind: it distracts future readers of our work and clutters the solution.”