I know I'll get pounded on this ...
but I'd like the question to be, how much ?!
What to comment about or what's necessary ? for almost every single line, that you're likely to see in the code PSC publishes. Or just reminders why a procedure has to work in one way and can't in another, abstract explanations about a process or idea where it's needed and isn't self explanatory, that you're likely to see in my code.
I don't think you'd want to dump the entire technical specs in the code. Not that I personally write technical specs. I only write functional specs and even that is only for none trivial jobs every once in a while.
Personally, I try to comment where I feel it's necessary but it really is hard, at least for me, not to mention time consuming. Writing in English and writing code are two very different skills, I really envy people that can.
It'd be interesting if someone remembers any worth while articles on the subject. I hang around @joelonsoftware.com quite often don't remember any articles like that.
I don't want to sound like a snob but most code I run across written by someone else are usually these horrible spaghetti code with thousands of patches that somehow still pull together, I'd be lucky if it's even properly nested, forget about comments. And most of the time I prefer writing the procedure from scratch, it's just quicker that way and a hell of a lot better.
Anyone that has worked on MFG/Pro would know what I'm talking about. QAD are one if not their biggest partners, I think, they're the biggest single reseller. It's not just that the code is a ****ing mess, we have these talks about code being elegant, it's a miracle it's even running.
Progress has been talking for years on how to build application and architecture etc. and QAD, probably, their biggest partner is the perfect example on how not to write code.