IssueRaiser

I mentioned it partly because it's addressed in the actual article, and the specific instance I referenced is such a flagrant abuse of th...

I mentioned it partly because it's addressed in the actual article, and the specific instance I referenced is such a flagrant abuse of the guideline: "Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the _working_ is obvious, and it's a waste of time to explain badly written code." It's almost as bad as: // Increment i i++; I think we should be aiming for code that is so beautiful and simple that it doesn't require commenting; comments should be left for exceptional circumstances in which something really can't be clearly expressed in the code. But that's definitely separate from documentation which should be separate, and at a much higher level.

Posted by oneeyedpigeon on Nov 26, 2014, 1:42 PM

Tags

Related issues

Raise real-world problems, find people facing the same issue, and discuss solutions.9,000 issues0 comments

hackernews (Other)

I mentioned it partly because it's addressed in the actual article, and the specific instance I referenced is such a flagrant abuse of th...

oneeyedpigeonNov 26, 2014, 1:42 PM

I mentioned it partly because it's addressed in the actual article, and the specific instance I referenced is such a flagrant abuse of the guideline: "Comments are good, but there is also a danger of over-commenting. NEVER try to explain HOW your code works in a comment: it's much better to write the code so that the _working_ is obvious, and it's a waste of time to explain badly written code." It's almost as bad as: // Increment i i++; I think we should be aiming for code that is so beautiful and simple that it doesn't require commenting; comments should be left for exceptional circumstances in which something really can't be clearly expressed in the code. But that's definitely separate from documentation which should be separate, and at a much higher level.

Comments (0)

No comments yet. Start the discussion.

Comment on this issue