[Ernest_at_the_Beach]

Right....Comments can suggest,...but one has to really study the code.

[altair]

Comments often do not get changed when the code they are documenting changes. Sadly, that's just the state of the art.

Probably the best change that we've gotten from Open Source are more programmers who write code that they expect other people to read. We're still a tiny minority, but every little bit helps.

I always try to put my own documentation into as colorful of terms as I can just as a reward to the reader. See my comments in src/emacs.c in the XEmacs sources which I've posted here before (labeled -slb).

As a bonus for straightening this out, XEmacs can now be run in place as a login shell. This never used to work.

See also the place in the same file where I pulled an Obama. Turn about is fair play. If all programmers treated code as it is meant to be - read by humans, the world would be a better place. Of course, I'm biased.