One of the biggest problems with commenting assembly code (speaking as
one who did it for many years on IBM mainframes) where on each line you
try to describe what the instruction does,is that there is a tendency
when reading the program later (either you or someone else) to read the
comments, and not the code. And if the comments are at all incorrect,
bugs galore can creep in when you modify stuff later.

The approach we always took here was to comment WHAT THE CODE DID, as
opposed to what the instructions did. One can assume that an assembler
programmer knows the assembler inside out (or else he shouldn't be
trying to modify the code!). But clearly explaining what the section of
code is supposed to do is far more useful.

Documenting code is an art, and is much harder than writing it in the
first place. After all, you KNOW what you are doing, so the tendency is
to explain things from your point of view, rather than that of some poor
slob (and it could be you!) trying to change it three years later.

This applies to code written in any language, not just cryptic languages
like assembler and C. Even "self-documenting" languages like (shudder)
COBOL are not really self-documenting. The individual statements are
easy to understand (but then to an assembler expert, so are assembler
instructions). It's the overall logic of the code fragment that needs to
be explained.

Ideally, the comments in your code should be the same, no matter what
language you are progamming in. If you wrote a program in "C", and then
decided to redo it in assembler for speed, the comments from your C
program should be able to be copied directly to your assembler program
and still be meaningful. Someone reading your program should be able to
figure out what the code fragments do, even if they don't know the
language.

My $.02 worth

Larry