[millstone]

Don't listen to this guy. Copious comments are great.

1. They act as a easier-to-skim narrative of the code. You can often get an outline of a well-commented component by reading the comments alone, rather than by picking apart a language designed for machine consumption. Syntax highlighting makes this especially easy.

2. They're helpful for other programmers who may not be as comfortable in the language as you are. For example, my PHP is about ten years old; I had no idea that `__construct` is the constructor, and not just another function. But thanks to the "useless" comment, I do know that.

3. They're helpful for programmers who aren't as comfortable in the problem domain. A line in a FFT implementation may be "obvious" to those skilled in harmonic analysis, but not the poor client programmer who is trying to figure out why the function is returning garbage output.

4. They can be useful as a thing to search for when you need to navigate around.

When deciding if I should write a comment or not, I ask myself a simple question: if I come back to this bit of code, will it be obvious why it’s been written this particular way? If my future self will be very thankful for an explanation, then it’s a no brainer, I write the comment.

Note the assumption that the code will only be consumed by "my future self".

Ever maintained someone else's under-commented or no-commented code? I'm sure the original programmer did not have any trouble with it, and will never know what he inflicted on his successors. Spend some time working in a comment desert, and you'll never complain about the rain.

[swanson]

Don't code for machine consumption, code for programmer consumption. Code is read 5x more than written, etc. Use function/method/class names that are readable like an outline.

Code comments are a poor teaching tool. Use a coding style guide/standard, pair programming, training, or a book to teach basic language idioms.

I don't buy the "searching argument". Ctrl+F for "account" will match a method named "lookupAccount" just as well as a comment that says "//lookup account". If you use a somewhat consistent naming scheme, it will probably be easier to search for something - try finding more than 2-3 words in a row in prose.

Putting so much perceived value and trust into code comments is like trusting "Architecture Design.docx" instead of looking at the actual running code.

[mattfenwick]

If "copious comments are great" is true -- does that mean we should write copious comments?

I'm talking about opportunity cost here -- the time spent writing comments is time not spent on the code, design, test, etc. So for me the question becomes what I should do to provide the max benefit for the least cost -- should I write comments, improve the design, fix up some code to eliminate special cases, test for corner cases?

Since it's an inherent trade-off, I don't see this as being an easy question to answer. Probably, there are multiple adequate answers.