I could write a dozen blog posts on code commenting: habits, effectiveness, philosophies…there’s a lot to say on this topic. But today’s is going to be short and sweet.
If you comment something out…tell me why.
I look at other people’s code all day, and the one thing that drives me crazy more often than anything else is commented-out lines…with no explanation. Why is that no longer in there? Were you trying to make it work, and couldn’t? Were you testing something? Did you determine that those lines were actually bad, and should be removed, but you didn’t have the sand to actually delete the lines, so you commented them out? Maybe it’s an either/or: sometimes you use line A, sometimes you use line B, and you comment out the line you’re not using. All of these are reasons (note I didn’t say good reasons) to comment out code, but unless you leave me a brief note explaining why you commented that code out, I’ll never know. I can’t read your mind.
As far as commenting habits go, this is really low-hanging fruit. In the moment you’re commenting out some code, you know why you’re commenting it out (otherwise, why would you be doing it?). A month from now, you may not remember. If someone else is looking at your code, chances are, they will have no clue. Take a few seconds — literally, that’s all it should take you — and write a quick comment.
In a related note, don’t feel bad about deleting lines, folks! That’s what version control is for. You um…are using version control, aren’t you? You are committing often, aren’t you?
Here’s another low-hanging fruit for you: if you catch an exception, and don’t do anything, explain yourself. Chances are you’re just being lazy, but you may well have a legitimate reason. I won’t know unless you tell me!
Originally posted November 2nd, 2011.