Andy, while I agree with you in general, I feel I have to play the devil's advocate a bit here. How exactly would separating the documentation from the code solve any of the 4 problems you listed below? As far as I'm concerned, a) and b), are a result of eternal procrastination, and c) and d) are a result of sloppiness. None have anything whatever to do with location, only with the attitude of the person(s) doing the documenting.

A person who will document, will document; and a person who will not, will not. Attitude, not location will determine what gets done.

When you argue the benefits of separation for the next person who has to review the code and docs, then I agree whole-heartedly.

Alan

>Hi Rick
>
>>Still considering most people don't document at all, I suspect code comments are a lot better than no comments <g>...
>
>Yeah, as I always say in my Optimization session: Most people optimize their code at the same time as they go back to add the comments <g>
>
>>I agree. I've always been a big believer that documentation doesn't belong in the code, but somewhere else - a doc system or whatever you use to document and comments are meant for understanding the code.
>
>Absolutely. In my experience attempting to document in code failes for one, or more, of the following reasons:
>
>(a) It gets left "till later" because the code isn't finalized yet
>(b) It gets left "till later" because the developer is heads down cranking out code and can't be bothered with writing up the documentation now....
>(c) It is written before the code and thus is a statement of intent, not documentation of what is actually happening
>(d) It doesn't get updated when 'minor' changes get made to the code so that it gets increasingly outdated and more and more irrelevant (if not actually wrong) as time goes by