Editorial note: I originally wrote this post for the Submain blog. You can check out the original here, at their site.

Why do we have the tendency to comment out code instead of just deleting it? The reason is that we don’t want to lose a piece of code that might come in handy in the future. Maybe we think we’re still going to need it because it solves some problem in an elegant way. Or maybe it’s because it helps us when debugging.

It all boils down to fear of losing information. But commented out code will get in the way more than it will help you, and it’s better off being deleted. I’ll expand on why below and provide some possible alternatives.

Why Commented Out Code Is a Problem

It Distracts

At the very least, commented out code will distract you and your team members from the actual code. It’s tempting to think our brains can filter out the commented blocks or that just a few lines won’t make our minds wander. But in reality, the commented out code is just an extra hurdle your brain needs to jump when trying to make a mental model of what the code is doing. And that by itself is hard enough, even in very clean codebases.

It’s a Source of Code Rot

More often than not, commented out code will start to “rot.” The longer code stays commented out, the higher the chances it no longer fits when uncommented.

One possibility is that it just doesn’t compile anymore. The codebase will likely have changed, and the live code will have evolved with it. But the commented out code will still be as it was when you put it in comments.

A more dangerous situation could arise if the code does compile but the behavior of any underlying code is altered. The commented out code may make calls to other components whose behavior has changed. This means the commented out code no longer does exactly what it was intended to do. That’s a potentially be a dangerous problem, and it means you’ll be wasting your time trying to find the cause of an obscure bug. In both cases, it’s a risk to the team and the company, and one that could have been avoided.

Finally, the commented out code may have been a good idea at the time, but fast forward several months or years and you can probably come up with a better solution. Languages, frameworks, and techniques evolve, and in time you will have acquired more knowledge, causing you to solve a problem in a different way. Trust your future self to solve the problem that the commented out code solved.

So how can we avoid the problems caused by commented out code without losing our piece of code forever?

What to Do With Your Commented Out Code

Commit it to Source Control

One option is to have the code committed to a source control system. This allows your code to remain clean and readable, without distractions. And your source control system will retain any historical pieces of code. If you want to know how something used to look, you can check the history. If you want to know why something was implemented a certain way, you can look at the commit log. But take note–this does mean you should take your commit messages seriously. You should not only mention what you did but why you did it.

Blog About It

But what if you just have a great idea that you don’t want to lose—an idea that could fix some potential future problem but doesn’t need to be committed to source control right now? Or maybe you’re afraid knowledge will get lost in the long commit history? Granted, sometimes it’s hard to find something you know is in source control, especially when the project has a long and large history of changes.

If you have a blog, your idea might make for a great post. This helps your blog by adding content, it helps other developers who encounter similar problems, and it can remain there for you to come back when you need it.

Add it to a Knowledge Base

A blog might help when it’s some general idea, but that won’t work if your idea involves sensitive information, crucial to the company. Or it might be too tied to the context of the application. In that case, you might consider setting up a knowledge base. Often, this comes in the form of a company wiki, but I’ve also seen it in the form of a GitHub repository or gist. Most of these solutions even allow versioning and comments.

Use Feature Toggles

Sometimes pieces of code need to stick around so they can be enabled at the request of the business. In that case, a feature toggle can help out. There are excellent libraries for implementing feature toggles, but in its most simple form, you can have a check for an application setting:

bool someFlag;
if (bool.TryParse(ConfigurationManager.AppSettings[“flag”], out someFlag) 
    && someFlag)
{
    // do something
}

When the time arrives to enable the feature, just change the setting to “true” and you’re good to go. The extra advantage of this approach is that it allows you to keep any tests running, avoiding the code no longer compiling or working as intended when uncommented.

But What About Debugging?

If you’re keeping code in comments, only to uncomment it when you’re debugging, consider some alternatives.

First, you could use compiler directives:

#if DEBUG
    // do something in debug only
#endif

This piece of code will only be compiled into your assemblies, if you’re in the debug configuration. The above example is for C#, but most programming languages have similar constructs.

Second, if you’re only trying to output some logging statements, consider log levels. Make sure you use a modern logging framework, and then use the relevant log level, as in the following example:

logger.Debug(“Some extra info here”);

You can then configure your loggers to, say, log all levels locally but only warnings and errors in production.

A final, little-known feature you can use is the DebuggerDisplayAttribute. It’s use like this:

[DebuggerDisplay("{Name}")]
public class Customer
{
    public string Name { get;set; }
}

Now, instead of displaying this when debugging:

You will see this:

Notice how my name is in the debugger popup instead of the type. This can be very convenient, especially when working with larger sets of variables (and collections!)

Declutter Your Code

There are no absolutes in life, and the same applies to coding. So sometimes you might still want the commented out code inside the codebase. But even then, there are superior options to just commenting out the code. Commented out code truly is just junk in your codebase, and most codebases are hard enough to understand already. Don’t add more noise.