[einhverfr]

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.

[randomdata]

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.

[einhverfr]

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.