Commented-Out Code vs Maintainability

Code comments are lines of source code which are added by humans in order to explain what's happening in the code to other humans; the compiler ignores these lines entirely when building the program. How comments are delineated depends on the language, but a many languages (including C#) do this by prefixing the line with two slashes "//".

In the process of writing and debugging code, it's not uncommon for programmers to temporarily "comment-out" lines of code (or even entire sections) by prefixing them with "//" in order to narrow down the location of problems or to experiment with different approaches. In ideal situations, the programmer cleans up these commented-out lines when finished. On occasion, a programmer will forget and some code will remain commented-out which should have been re-enabled. If this results in a bug, the fix is usually as simple as un-commenting the code.

One common use (or rather, abuse) of comments is as a feature switch. In other words, instead of creating a mechanism to enable/disable a feature through normal program configuration, the programmer simply comments out the code for the feature. Re-enabling the feature requires that the code be changed and the application rebuilt.

Another common abuse is to enlist the comments as a way to retain code which the programmer may want again in the future. Perhaps the programmer is working on a fix for a bug and needs to make changes to some code. The programmer doesn't want to lose the old code (either because it may be useful somewhere else, or because the fix may not work and the code may need to be put back into its original state). So the programmer simply comments out the old code, leaving it in the source code file to be found later if needed.

Both of these abuses can lead to long-term maintainability issues. The problem is that a programmer new to the code (or one who hasn't seen the code in question for a while) can't necessarily tell why a particular piece of code is commented-out. Was the code accidentally left commented-out? Was the code intentionally commented out to disable a feature? Is the code simply an older version of an algorithm? Was it a forgotten debugging attempt? Is it being left in for historical purposes?

Additionally, this (possibly) vestigial code makes the code less readable and pollutes search results for programmers who are trying to find particular code when debugging.

Both of these uses for comments have better alternatives. Switching features on and off should be done by the application's configuration mechanism; this makes it easier for the feature to be turned on and off (since the code won't need to be modified and rebuilt) and removes any confusion as to why the code is commented-out. Experimenting with a solution which may need to be reverted and keeping older implementations in case they need to be used again in the future are both problems which are solved more efficiently and safely by the version control system.

Typically, large swaths of commented-out code in an application's code base are a symptom of larger problems with version control. It can mean that version control is not being used at all, or that the programmers working on the application do not understand how to use the features of the version control system. It's closely related to the problems with code bases having sub-folders and files with labels like "BACKUP" on them - programmers are experimenting with possible solutions to problems without a safety net in place.

When commented-out code is polluting a code base, the solution is actually very simple. Place the code under version control and delete the commented-out code. If you ever need the commented sections again, you can always retrieve them; if not, they're out of your way.