> -----Original Message-----
> From: IBM Mainframe Assembler List
<snip>
> Lest I be misunderstood, let me repeat my point. Explicating
> what instruction sequences do is not the proper function of
> comments. The instructions do this job themselves better
> than any dubious natural-language paraphrase can do it. The
> proper function of comments is to motivate instruction sequences.
>
> John Gilmore Ashland, MA 01721-1817 USA
Total agreement! Comments are not to explain what the instructions __do__. The
instructions do what they do. If that is desired, just have a "pointer" to the
Principles of Operation. The comments should explain what is desired and
perhaps the algorithm. The reader can then evaluate if the instructions
actually accomplish the objective or do so efficiently.
IMO, a good comment would be something like:
**
* SCAN THE BUFFER FROM HIGH TO LOW, LOOKING FOR X'A0' CHARACTERS
* ON ENTRY, R1 POINTS TO THE BEGINNING OF THE BUFFER, R2 POINTS
* TO THE LAST BYTE IN THE BUFFER. R3 IS USED AS A WORK REGISTER
**
LR R3,R2
LOOP DS 0H
CLI 0(R3),X'A0' FOUND VALUE?
JE GOTIT YES
BCTR R3,R0 BACK UP ONE BYTE
CLR R3,R1 OUT OF THE BUFFER?
JNL LOOP NO, CONTINUE
...
GOTIT DS 0H
--
John McKown
Systems Engineer IV
IT
Administrative Services Group
HealthMarkets(r)
9151 Boulevard 26 * N. Richland Hills * TX 76010
(817) 255-3225 phone * (817)-691-6183 cell
[email protected] * www.HealthMarkets.com
Confidentiality Notice: This e-mail message may contain confidential or
proprietary information. If you are not the intended recipient, please contact
the sender by reply e-mail and destroy all copies of the original message.
HealthMarkets(r) is the brand name for products underwritten and issued by the
insurance subsidiaries of HealthMarkets, Inc. -The Chesapeake Life Insurance
Company(r), Mid-West National Life Insurance Company of TennesseeSM and The
MEGA Life and Health Insurance Company.SM
