I had written some code that was hard to understand. So I wrote a comment to explain how it was supposed to work. I come back a couple months later, and guess what? The comment might have made complete sense to the guy who just wrote the code, and therefore already understood how it worked. But to someone who didn't it was completely opaque, and therefore only served to make me more irritated the person who wrote it. (i.e., me a couple months ago.)
So that's why I don't like that style of comments. If the code alone doesn't make sense, then 90% of the time the comments that try to explain it don't make any sense either. Maybe the only situation where this kind of comment is acceptable is if you have to use some hairy dynamic programming algorithm or something like that, in which case the comment should just be the name of the algorithm and a URL for a page that explains it.
I had written some code that was hard to understand. So I wrote a comment to explain how it was supposed to work. I come back a couple months later, and guess what? The comment might have made complete sense to the guy who just wrote the code, and therefore already understood how it worked. But to someone who didn't it was completely opaque, and therefore only served to make me more irritated the person who wrote it. (i.e., me a couple months ago.)
So that's why I don't like that style of comments. If the code alone doesn't make sense, then 90% of the time the comments that try to explain it don't make any sense either. Maybe the only situation where this kind of comment is acceptable is if you have to use some hairy dynamic programming algorithm or something like that, in which case the comment should just be the name of the algorithm and a URL for a page that explains it.