Wait until you start working on multi-million line systems in companies where nobody - and I mean nobody - understands everything, and the original authors of pretty much every subsystem has since left the company; and you need to fix 20 critical bugs in the last week before the thing ships. Clues that are more high-level than the code can ever be start being really helpful.

> I've never met a function that I wish had [comments]

Come on, this is stretching credulity. Either that or you don't value your own time.

First, I think that requiring the reader to know the code in depth is a good thing. Comments should not be used to avoid this. Comments can decay in relevancy and, aside from function API documentation, should not be used in debugging. The way comments should be used is:

1) API documentation says this: does the code conform? If not, either the specification is bad or the code is bad.

2) Comments inform collaboration, but do not inform debugging other than as API documentation.

I do agree that there is merit to documenting public interfaces, but there are tools designed specifically for that job so that you do not have to go slogging through the source code at all when you want to look up a definition.

As a result, I feel that is a different matter to commenting for the purposes of code maintainability, which is what the parent poster is speaking to.

We are probably on the same page. I wrote this:

http://ledgersmbdev.blogspot.com/2012/08/patterns-and-anti-p...

Comments are not for maintainability.

> Is that a problem?

Yes, because it means I might need to read 6 layers of code and wind through multiple modules, instead of just reading the top layer that defines the invariants of input/output for a module.

I don't think people here are against commenting APIs... That's more of a documentation thing.

It's not just a documentation thing.

When you document an API you make a promise to the programmer. If you use the API according to the documentation, the API will behave according to the documentation. Documentation of API's establishes interfaces. If the code doesn't conform to the comments describing the API, it is the code's fault not the comments' fault.

I don't think people here are even against commenting code. I think people here are against (and for good reason!) duplicating coding logic in comments designed to describe in line-by-line detail the code that should have been readable in the first place.

Comments like that are FAR worse than no comments at all. If there are no comments at all, a new comment that is clear and relevant will be read. If you have a codebase full of bad comments you cannot start adding good comments until you clean that up.