Tim X  <timx@nospam.dev.null> wrote:
+---------------
| My experience has been that most code comments are next to useless.
| How often do you see something like
|     x = 10        // set x to 10
| Maybe slightly exaggerated, but you get the idea.
+---------------

Far too often, unfortunately.

The TOPS-10 5-Series Monitor Coding Conventions (LEVELD.MEM)
prescribed a comment on every line [but this *was* all in
assembler, after all!]. But the rule was that you *never* used
the comment to describe *what* an instruction did -- the reader
is presumed to know the language in question -- but *why* the
instruction (or short sequence of instructions) was being used,
or other higher-level information such as particularly tricky
algorithms.


-Rob

-----
Rob Warnock			<rpw3@rpw3.org>
627 26th Avenue			<URL:http://rpw3.org/>
San Mateo, CA 94403		(650)572-2607