

Stop Commenting Your Code, Please. - cschanck
http://designbygravity.wordpress.com/2009/10/25/stop-commenting-your-code-youre-just-confusing-things/

======
mkelly
The types of comments I've found useful are ones that explain "why". Either
summarizing a function or class at a high level (why I should use this thing,
why it exists), _or_ explaining a single line iff it's highly counter-
intuitive. e.g.,

"This is a Foo to replace the broken one in the Bar library, which doesn't
frotz Baz correctly." "Yes, we actually have to do this because Qux isn't in
magic mode yet."

I figure a comment is worth it if it's highly likely to save someone from
ripping out/changing a section just to see why it's done that way (which is
sometimes a fun exercise, but mostly just reminds you of some subtle detail
you forgot).

~~~
thismat
A friend of mine always says "Your code should explain what it does, comments
should explain why.". I agree with with you and him completely.

------
wglb
After reading "Refactoring" by Martin Fowler, I would say "comments are bugs".
I still operate that way, excepting a one-line description of a function or
class. In rare situations, a longer explanation of convoluted code is called
for.

Yes, I am still trying to reconcile this with "Literate Programming",
unsuccessfully.

