>>I think that method headers have their place. The most important thing they do is provide a huuman-readable version of the interface - what parameters does the method (/function/procedure) accept/require and what does it return.
>
>For absolute sure. If the parms are undocumented in a method, I am in favor of small yield tactical nukes to remove that developer from the gene pool.
Hey now, failure to use comments is nurture, not nature. IOW, good practice can be learned- no need for the death sentence. :-)
Seriously, comments that explain parameters follow the same guidelines, IMO. With descriptive variable names, often a comment explaining the purpose is completely unneeded.
I don't have my code reviewed by peers as much as I would like, so I don't really know if my code is horribly unreadable- but I use comments pretty sparingly, and rely heavily on descriptive routine and variable names to explain what's going on. I usually reserve comments for unintuitive logic sequences- the rest is simple and understandable by design. I've seen some really horrible code that's meticulously documented, and it's still difficult to understand.
Erik Moore
Clientelligence