I’ll Delete Your Commented Code Without Reading It and I’m Not Sorry

I was knee-deep in a mess of undocumented legacy code. I wasn’t even sure who had authored this code, but whoever it was, they had long departed to places unknown. The code was in a language I didn’t even really know. And the bug was marked “critical.” If I didn’t fix it, an entire academic department website would display totally incorrect information.

It was then I encountered the “thing.” A large commented out block of important-looking code. Was it left behind by an ancient civilization? Could it help me? Or was it a beast placed into a jail of a comment block to protect innocent coders?

I call this “comment junk,” and my life’s mission is now to delete as many of these trash piles as possible. Here’s how I do it.

I’d estimate that 75% of the time these are just useless garbage. It’s code that will never be used again. It was something someone did in the past and then abandoned. It’s irrelevant.

Sadly, most comment junk doesn’t exactly have a comment telling you this. I mean, who would admit something is useless and just leave it there?

If the person who wrote it is still around, I’ll ask them what to do with it. If not, to the delete button the commented code goes. I know it’s scary, but the odds are that no one will ever need it. And if they do, it’s in version control, right? RIGHT????

I do this two ways: by having a standard for comments and by using a code review tool that catches bad ones. An example of a good standard is GhostDoc comments, which have a standardized form. You can use comments in this form to generate documentation. GhostDoc also can create the basic comments in the first place based on a template, so developers know what they need to include.

/// <summary>
/// Moves the piece.
/// </summary>
/// <param name="origin">The origin.</param>
/// <param name="destination">The destination.</param>

 

There are even ways to do this in CSS! And CSS is one place where I see the worst examples of commented-out code. I often use KSS for this process, which can generate a style guide based on the comments:

/*
A button suitable for giving stars to someone.

:hover             - Subtle hover highlight.
.stars-given       - A highlight indicating you've already given a star.
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
.disabled          - Dims the button to indicate it cannot be used.

Styleguide 2.1.3.
*/

Once you have this standard, you can configure your code review tools and linters like Code.It.Right to catch any comments that don’t meet it.

One time, in the middle of developing a large website, the project manager informed us that the client wanted to put a certain feature in the backlog. It was an event-mapping feature and part of many pages. Like, it was prominently displayed on the front page. Unfortunately, we’d already done a lot of development on it and were pressed for time.

Initially?we just commented out the code, but as development proceeded, this “comment junk” became an eyesore. So we uncommented the code and just used, well, code to turn it off. Meaning that if the front page had a space for it, but that data didn’t exist, the page didn’t display it.

In the project’s Confluence knowledge base, we created a page for that feature. The page described the feature and how to finish implementing it. After the initial release, I handed the project over to a junior engineer. The work we did to document this feature allowed them to easily pick up development.

We also could have put it in its own Git branch, but as the other code had changed, it would have been challenging to sort out. This approach forced us to become more modular.

For code that’s used in debugging only, or in the very rare case you need to turn a feature on and off in code, I recommend you do that with, well…code! For my own code, I make sure the debug and features can be turned on and off in a configuration file, not by commenting out code.?Of course, you say. This is just a simple application and no one will be extending it. But you never know!

Having a single file for this type of configuration makes this change easy. It also gives people working on it an idea of what configuration options are available. I can’t tell you the number of times I wrote my own debug code only to be later told, “Oh yeah, there was a debugging thing I wrote in this file you didn’t look at.” Previously on our blog, Peter Morlion described some other common methods for handling this.

Goodbye, Comment Junk