Documentation is for computers to read (or: Commenting Code is Evil)

http://gilesbowkett.blogspot.com/2007/12/documentation-is-for-computers-to-read.html

by kapitti • 18 years ago

1 5 18 years ago

gilesbowkett.blogspot.com

kapitti• 18 years ago

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• 18 years ago

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.

FreakPerf• 18 years ago

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.

chuckm• 18 years ago

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.

jimrandomh• 18 years ago

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.

Documentation is for computers to read (or: Commenting Code is Evil)

Related Stories