All right, step away from the double slashes and no one will get hurt! Over the years, I’ve seen plenty of bad commenting practices, and I’ve been guilty of doing some of these, myself, but it’s time for us all to just move on and simplify our code in the process. Consider each of these a type of smell in the code, to the point where the code can smell like New York City after a month-long sanitation strike.
Here they are, listed in no particular odor (pun intended):
Commented out code
Why, oh why, do we need to keep commented out code in our production code? Even in the days before source control was common, this was an insidiously evil way to mire down maintenance programmers, or even yourself. Now that we use source control on a regular basis, there really is no need to keep hanging onto this stuff.
The problem is, most programmers will just leave commented code right where it is. Partly, this is simply out of fear – fear that somehow the code has meaning, it might still be needed, or it’s something someone was working on. Another reason programmers won’t delete the unneeded stuff is they simply don’t feel it’s their responsibility (“if it ain’t broke, don’t fix it”). New programmers will think that leaving in commented out code is some kind of standard, and they will start doing it all the time, as well. After a few years, some files may consist of almost as much commented out code as real code, if not more.
The fact is, commented out code doesn’t do anything, so it’s really just visual noise. It makes real code harder to read. Commented out code shows up in searches, which can cause a little extra confusion. It also makes it a bit more difficult to do code compares.
So, just say no to commented out code. Go ahead, rip it out. No one will miss it. If anyone truly needs to reinstate it some day, it’s right there in source control. They can copy-paste it right back where it was, and probably discover all over again why it was commented out in the first place.
The historical marker comment
Here’s an example of this type of comment:
if (index < maximum) // Added 1/1/2014 XYZ
These comments are completely unnecessary, assuming you’re using source control. Then, we can see who to praise or blame, as the case may be. As with commented code, this stuff can really start dragging down the readability of the code, without adding a single useful tidbit of information about the code.
These comments can be found decorating the end of do, if, while, for, foreach (or the equivalent), enum, struct/type, switch/select statements, and even methods or functions. If you’re not sure what I’m talking about, pay attention to the comment at the end of the while statement:
while (index < 100)
// Do some stuff for the next 2000 lines…
} // while (index < 100)
Maybe you really do need to see that comment to let you know when your 2000-line while loop is finally over, but if that’s why you’re doing it, there are now two reasons why we’re going to send you to bed without your video games, your iPod, your Droid, or your quad-copter.
The bottom line is, if you keep your methods and your block statements short, it should be no problem for the average programmer to see both where a block starts, as well as where it ends.
These comments actually add more density to the code, making it harder to read. On top of that, they do not add any new knowledge to what or why the code is doing what it’s doing. Worse, when people change the stuff going on in the top statement, they frequently forget to update the comment. And if you have nested block statements and discover you need to swap things around? Yep, you have to make sure the comments go along for the ride. In other words, using these comments also adds to your maintenance woes.
Keep your code blocks short, and just get rid of these comments. After a while, you’ll find you don’t miss them.