>I think there is quite a difference between documentation per se and (inline) code comments. In particular, (inline) code comments are intended to supplement the actual code and to spell out things that are not readily apparent even if identifiers are appropriately chosen, like the intent of a particular fragment, exploitation of obscure language/runtime features or confluence of certain events (like the fact that testing for EMPTY(SomeField) trivially covers EOF), or why some piece of code was mutilated during maintenance. I.e. things that are non-obvious but relevant.

Absolutely and inline comments shoudl be used all the time and liberally. I comment everything that isn't 100% obvious, although I do admit that I often fall into the heads down coding of the moment mode like Andy describes and only on the second pass go back. Inline comments for code are a must and there's nothing that can replace that IMHO.


>The value of such commentary greatly depends on it being present where it is needed and absent anywhere else. Also, comments must be maintained just as the executable code lest they become worthless and misleading; the chance of comments getting out of sync with the code during maintenance is directly proportional to their degree of redundancy. With the monstrous function headers suggested elsewhere in this thread you'd be lucky if they bore some semblance to reality even during initial coding, much less during maintencance. Not to mention relevance ...

Are we talking about hte same thing here though? When I mean inline comments I'm talking about process, where as documentation refers to function. Process is geared for the producer the coder, while the documentation is done for the consumer of the code...

I usually do a two step process. I document some base information with the method header (if it's not entirely obvious) and then doc the whole thing elsewhere (Help BUilder in my case). If I build something that gets moved to a lot of developers I often go through the moves of synching code docs and help document but I actually am leaning away from that these days because it's just too much work and as you say easy to make changes in one place and omit the other so the docs become stale.

It's crucial to have docs in one central place so that the data is consistent!

+++ Rick ---