News for hackers. Stuff that matters.
Re:Documentation is for computers to read (or: Commenting Co... by jimrandomh on Tuesday December 30, 2008 @02:40PM (#414566)
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.

There are no comments on this comment yet.