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.

Over time, developers change the active code but tend to leave commented-out portions untouched for the fear of disrupting some unknown important commentary or useful alternative logic. For example, variables might get renamed and functions get refactored. As the active code surrounding commented-out code drifts away, the commented-out code tends to become increasingly incorrect or irrelevant, and it might take nontrivial effort to re-enable the commented-out code. So even if code gets commented out with the best intentions in hopes of being useful sometime in the future, the opposite ends up happening and it becomes a deadweight as its context changes.

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.

If you still want to commit unused code despite these arguments against it, sometimes there are ways to do it relatively safely. In a statically typed, compiled language like C/C++/Java/Rust, hiding code within an if (false) { ... } block will still subject the code to all the usual name and type checking at compile time. Similarly, this approach works for TypeScript during compilation and Python during optional static type checking, but does not work for plain JavaScript or only running Python code. There are a handful of caveats, however. Not all code can be disabled – for example, you cannot make variables and functions exist or not exist based on an if-block. Code that relies on reflection will generally not be protected by compile-time checks. And the more common idiom in C/C++ of using #if 0 has no compile-time checks either.

More info