Update: I was asked what I thought good com­ments were, so here’s a fol­lowup post to this one: Update on stu­pid code com­ments: good code com­ments.

One of the most frus­trat­ing things any pro­gram­mer can do is work with some­one else’s code. Some­times, if the code is well-written, you can learn some­thing and it’s a reward­ing expe­ri­ence. Most of the time though, if you’re stuck with main­tain­ing some­one else’s appli­ca­tion, it’s because they didn’t do a good job and you’ve been sad­dled with fixing/completing/maintaining it.

On the other hand, I have work­ing appli­ca­tions “in the wild” that I would be mor­ti­fied for any­one else to see, under the hood.

I’ve had both good and bad expe­ri­ences with other people’s code. At the moment I’m work­ing with some code that’s not bad, on the whole. But it’s cursed with one of my spe­cial pet peeves: stu­pid com­ments. Obvi­ous, point­less and use­less com­ments. “D’oh” com­ments. “No shit, Sher­lock” com­ments. “O RLY” comments.

Some exam­ples:


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


So it just me? Do other peo­ple wish that the orig­i­nal pro­gram­mer had spent less time writ­ing point­less com­ments and more time doc­u­ment­ing their logic? Or am I being overly anal again (you can tell me, really). Do you have favourite found comments?