

Documentation is for computers to read (or: Commenting Code is Evil) - kapitti
http://gilesbowkett.blogspot.com/2007/12/documentation-is-for-computers-to-read.html

======
jimrandomh
It's never so simple as "comment more" or "comment less". Some things are best
explained by identifiers, and needing to comment them is a sign of poor code.
On the other hand, some code requires domain-specific knowledge to understand
why it does what it does, and as much of that knowledge as possible should be
spelled out (or at least cited) in comments. I have written modules where no
comments were needed anywhere. On the other hand, I have written modules where
every line required a paragraph, a figure, and a short proof. The best
guideline is that comments should say as much as it's possible to say without
going off topic or repeating things that are obvious from the code.

------
kapitti
This is a very frequent discussion in my circle of hackers - to comment or not
to comment. I'm on the "not to comment" side of things; either your tests or
your code should speak for itself, if it's so complex that you need to leave a
comment - you're doing it wrong.

I haven't seen this discussion on HN yet - so I wanted to get the opinion of
so many people that write code day in and day out and may be responsible for
maintaining code they haven't written themselves.

~~~
michael_dorfman
Sorry, but I don't buy the whole "if it's so complex that you need to leave a
comment - you're doing it wrong."

Take, as a counter-example, any of Knuth's literate programs. Do you really
want to say he's doing it wrong?

Some things _are_ that complex. And sometimes, the best way to make sure that
the code is understandable is to add some human-readable text.

It's naive to think that humans and compilers should both be able to parse and
comprehend the same text with the same ease.

------
chuckm
I disagree. I think comments are often overused but I'm not convinced that
code and tests are expressive enough to always convey why functionality
exists.

For example, sometimes limitations in third party dependencies force you into
adding additional code that might look out of place or redundant. In cases
like this it can be hard to capture why this code was introduced without using
a comment.

------
FreakPerf
Commenting code is really hard work. I prefer to focus on the code. But if
you're working in a team.. I think it's better to comment to safe time in
future.

