Comments Never Get Out of Date

March 13, 2011 John Blanco Uncategorized

This blog is a response to Riyad’s assertion that comments are a waste of time. It’s definitely worth a read, but the gist of it is that code documents itself and that comments are more likely to fail than help. It’s sometimes true, but so is just about everything. :-) Reality can get in the way, though.

In every programming class I took in college and just about every language book I’ve read, one of the first things you learn is how to create comments in your code. In fact, in those college classes, if you dared hand in code without comments, you got dinged severely with “Explain what this does!!!1!!1!one”

Riyad Mammadov makes an excellent assertion that comments can make our code worse. He echos the words of Uncle Bob Martin, famed software author and surprisingly rabid Tea Party fanatic, that comments quickly become outdated when the code below them changes. I agree with this and I comment far less often than I used to.

Unfortunately for all of us, that doesn’t mean comments are obsolete. I’d like to take Riyad’s key argument and reverse it on him if you please.

What his key argument is is that comments would be great if (A) they changed along with the code they refer to and (B) if the developer had writing skills. I’d say both of those are often no’s. However, not leaving comments equally assumes (A) the next developer that comes along understands the original intent of the code and (B) that developer has naming skills.

What I’m saying is that encouraging a developer to skip the comments in lieu of writing good code will likely result in that developer gladly not writing the comments but thinking(mistakingly) that they are writing good code to make up for it.

Sound familiar? It’s the same reason many converts to the Agile Methodology are so happy to hear they can stop writing documentation, and do, all while both their code and the shipping product continue to look just as they did before. So much for that.

Case In Point

I’ve never met a developer who’s as good as they say. INCLUDING ME. I don’t believe you should comment every line or group of lines of code if the code is obvious. But, if you’re writing a blurb of algorithmic logic, leave a note on what it’s doing, and perhaps the math behind it, to ease the next person’s load. An example:

Quick, what does this code do? Maybe you can figure it out easily, maybe not. I’d like to think that a few seconds’ glance would tell you:

1. The loop iteration is backwards because we’re searching backwards.
2. When we find what we’re looking for, we capture a reference and end the loop.
3. We’re doing a date comparison of some sort.

I don’t think the date comparison is inherently complex. However, I think this sort of code segment can make quite a few developers stop and look — for a while. As you read this code, did you find yourself trying to unravel the date comparison? Did your mind silently work it out…

OK, the game date is compared to the week start date, and if the game date is greater than the week start date…uhhh, it’s coming after it…and we’re looping backward, so it meeeeeans it wasn’t after it previously. So, now it is….wait, isn’t it always greater than the start week? Oh, right, it’s not greater than the weeks after. OK, I got it.

It’s understandable. The backwards looping along with the date comparison being greater than is a little weird to digest. It’s the same reason we can have a little bit of trouble reading Ruby code that uses unless rather than if. We like to read left to right, we like our logic positive, and we like to ordering things chronologically. And that’s why when I see unless in code I just say if not in my head. :-)

Now, here’s the same code with a simple comment:

Simple question…if you were reading this code and came across this comment, wouldn’t it have saved you some mind time? Now, there’s a chance the comment may not have been accurate after a period of time. Perhaps someone came along and changed the logic but didn’t update the comment. But, what if the code had then become this?

Uh oh. After a quick inspection, the comment is out of date because that code is clearly searching chronologically. But wait! The loop is still decrementing! Because the comment gave you some historical insight, you can quickly deduce that someone tried to change the loop order but bungled the iteration (and the logic). That comment being out of date was still useful!

No, this may not always be the case. But let’s be serious. We always need to write clean, well-named code. And comments can’t hurt. Assuming a comment speaks for the code accurately is as silly as assuming a function does exactly what its name says it does.

I’ve never met a comment I didn’t appreciate when it adorned some tricky logic. Accurate or not, it will give you a clue as to what you’re looking at. And if you think your code is so hot it doesn’t need commentary, well, it’s not your opinion that counts here.

Coding Standards Are a Farce! Iron Chef America: Mozzarella!