Project Nayuki

Don’t share commented-out code

Programmers frequently comment out code during the course of their work. Beginners often pick up this behavior without conscious awareness, either from reading existing codebases or from straightforward deduction. Commenting out code is useful for quickly disabling some logic, adding alternate code, testing the changes, and swiftly reverting back to the original code by deleting the additions and un-commenting the old parts.

But I strongly discourage the act of committing, publishing, and/or sharing any commented-out code. That is, commented-out code should not be saved in a permanent version control system, be published for the general public to read/modify, or be shared with team members / project collaborators. Commented-out code should only exist as a temporary and private thing, not to be seen by other people or by yourself at a later time.

When a piece of code is commented out, only the person who did it understands why. It becomes noise to everyone else – it is not functional code, it provides no insight, it takes up valuable visual space, it needs to be consciously skipped over, and it ends up harming reading comprehension. Only the commenter knows why the code was disabled, how long it needs to be kept for, and what has replaced its functionality. Hence, to introduce commented-out code into a codebase is a selfish act which puts your own convenience ahead of readability for everyone. Moreover, even the person who commented out the code will forget their own reasons if they stay away from that section or project for a year; they end up hurting themselves in the long run.

Commented-out code reflects very poorly on the person who commented it out. It shows that they either don’t have version control set up for the project, they don’t have the skills to use it, or they aren’t comfortable with completely trusting code history to it. It shows their insecurity about whether a code deletion or change should be made permanent, because they feel comforted in seeing the old code in front of them and in the fact that it can be un-commented easily.

The phenomenon of commenting out code creates poor diffs for version control systems. If code is being disabled, it is clearer to show this by deleting code rather than by inserting comment marks. Worse, if block comments are used, then only the start and end of the comment are marked, but all the middle lines are being disabled without showing a diff. Similarly, it is better to change code directly instead of commenting out the existing code, making a copy, and changing the new copy. Finally, the act of removing commented-out code is far removed from the act of commenting out the code in the first place, thus generating more poor diffs. For these reasons, commenting out code is a very bad practice when combined with proper version control.

My message is clear: You should never commit commented-out code, you should never publish it, and no one else should ever see your commented-out code. When you make changes to code, you must fully change any relevant code and delete all code that is no longer needed, without preserving a copy of the old code on the side. You need to rely on version control to preserve and to retrieve historical code. If I ever work on a project and encounter your commented-out code, there is a good chance I will give you a stern warning and point you to this page.

More info