Well written software needs few comments

If you said no comments I would have to agree. But well written, structured code shouldn't have needless comments.

// save the file
file.save();

// close the file
file.close();

If you said no comments I would have to _disagree_.
d'oh

Well, that's obvious steven.

But I think there's more going on here. SICP (which is the best computer book ever written) suggests that code is the programmers chief communication mechanism.

I believe that.

I also think that comments tend to be maintained less than code, or out of step with code.

Of course, all those things can be mitigated by having a good project manager. I've been following emacs development closely just recently and saw rms crit some code destined for emacs trunk because it didn't have enough comments.

I know very well that while rms is looking after emacs he will ensure that all the comments are maintained as well as the code.

But that isn't always the code. In fact, it's the only personal example I have of commenting being entirely a safe maintainable thing to do.

I really don't find these kinds of comments useful.

// save the file

file.save();

I'd much rather read a summary that tells me the goals of a class or function and how it fits in with the system. Summary comments don't suffer rot as quickly as direct inline comments.

I also like to see comments on code that works around, say a virtual machine bug or something of that nature.

fewER comments, anyway.

It needs few/no comments to explain what it's doing.

But it still needs comments to explain why it's doing it, and why that way.

+1 Alistair
Furthermore, well-written code is not always read by the most clueful people. Sometimes, they need that helpful hand.

But yeah...

// close the file

file.close( );

is pretty dumb.

Documentation, yes. I prefer to see inline comments only in two scenarios...

a) they constitute documentation (function/method pre/post conditions, argument interpretation, return values, etc); OR...

b) if a function/method is being called that might induce side-effects that will affect the current function/method's execution flow.

For the record, object-oriented programming and stateful-object programming do not belong in bed together. If you have a sorted list, and it has a setSortOrder() method, YOU ARE DOING IT WRONG. If you have an Excel-style Workbook object, and it has operations like SetActiveSheet(name) and SetActiveCell(address) and EditActiveCell(newvalue), YOU ARE DOING IT WRONG.