Update: I was asked what I thought good comments were, so here’s a followup post to this one: Update on stupid code comments: good code comments.

One of the most frustrating things any programmer can do is work with someone else’s code. Sometimes, if the code is well-written, you can learn something and it’s a rewarding experience. Most of the time though, if you’re stuck with maintaining someone else’s application, it’s because they didn’t do a good job and you’ve been saddled with fixing/completing/maintaining it.

On the other hand, I have working applications “in the wild” that I would be mortified for anyone else to see, under the hood.

I’ve had both good and bad experiences with other people’s code. At the moment I’m working with some code that’s not bad, on the whole. But it’s cursed with one of my special pet peeves: stupid comments. Obvious, pointless and useless comments. “D’oh” comments. “No shit, Sherlock” comments. “O RLY” comments.

Some examples:


<cfml>
<!--- loop over the query --->
</cfml>
<!--- display message --->
#message#
<!--- check if matches were found --->
etc


So it just me? Do other people wish that the original programmer had spent less time writing pointless comments and more time documenting their logic? Or am I being overly anal again (you can tell me, really). Do you have favourite found comments?