Commenting variables (was: Definition of boolean)

[Doug Gwyn]

In article <1629 at goofy.megatest.UUCP> djones at megatest.UUCP (Dave Jones) writes:
>  But if you know what the variables are supposed to mean, then you
>  know what the routine *has* to do.

This is a good point: practically every variable should have a well-defined
meaning exhibited by an attached comment.  That also suppresses the
inclination to "borrow" an already-declared variable for some other purpose
instead of declaring a new one.

I agree that obvious algorithms don't require comments explaining them;
however, frequently (at least in my case) there are non-obvious things
that the code maintainer needs to know about many of the algorithms, so
some explanation is in order.  Also, it helps to document the general
intention of pieces of the code:
	/*
	 *	Sort in descending order of size.
	 */
particularly when one would have to do a fair amount of work to figure
it out from uncommented code.