I’m always pleased when I see developers commenting code. It means there’s something there that should be commented so the next guy will know WTF whoever wrote it was thinking. However much like any FOX special, there are times when “Comments Gone Wild”. I present some production code that contains some more, err, useful comments that I’ve found.
// Returns: Position of the divider
// Summary: Call this method to get the position of the divider.
Hmmm. Glad that was cleared up.
// Summary: Call this method to refresh items in the list.
Again. Good to know.
// Summary: Call this method to remove all items in the list.
Whew. For a minute there I thought we would have to spend some serious debugging time hunting down this method.
And my personal favorite…
/* this next part does something cool; don't even try to understand it*/
(i_love_lucy_is_on_tv turned out to be a boolean variable set to false). Go figure.