Re:Thoughts on being a programmer
by randomdata on Wednesday August 15, 2012 @12:04AM
(#4384531)
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.
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.