YES!
If necessary I'll write pages of comments for a single instruction. And
documenting before coding is sound doctrine.
One caveat s that a comment that does not improve understanding is a hindrance,
and I've warned students that I'll take of points for a comment like
LA R7,666(,R7) Add 666 to register 7
Instead explain why you are adding that value to that register.
--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3
עַם יִשְׂרָאֵל חַי
נֵ֣צַח יִשְׂרָאֵ֔ל לֹ֥א יְשַׁקֵּ֖ר
________________________________________
From: IBM Mainframe Assembler List <[email protected]> on behalf
of Jonathan Scott <[email protected]>
Sent: Sunday, August 24, 2025 6:39 AM
To: [email protected] <[email protected]>
Subject: Re: Execute-Type Instructions
External Message: Use Caution
I totally agree that in most cases performance is achieved by using the right
design and algorithms. Simplicity and reliability of code is also very
important, and for code which is not performance-critical there is little point
in attempting local optimization at the expense of simplicity. It is usually
only for extremely intensively executed code (innermost loops) where any sort
of local optimization is worth the effort. It used to be that reordering
sequences of instructions to avoid address generation interlocks and other
pipeline blocks could achieve significant improvements, but recent IBM Z
processors now handle much of that automatically. Keeping things in registers
(including vector registers) to avoid storage access is still useful, and some
newer instructions can help simplify code as well as improving performance, for
example the "interlocked-access facility 1" makes it simple and fast to use ASI
to update shared counters. The IBM Z hardware people have always said that you
should use obvious standard sequences of code as those will be the ones that
they are trying to optimise, so for example exclusive-or of a storage location
with itself is typically interpreted as an instruction to store zeroes in that
storage, and the standard MVC with offset of 1 byte is interpreted as an
instruction to fill storage with a pad byte. There are a few performance
oddities that are worth noting at the algorithm level, for example if you
repeatedly look at the same offset in many 4K pages you may get performance
degradation because there are only a limited number of cache lines for each
256-byte range, so it may be better to maintain a separate compact index
containing the same information.
And comments are essential not just for future readers of the code, but also to
ensure that the person writing the code can explain what they are doing,
ensuring they have a full understanding. I generally wrote the block comments
before I wrote the code. Back in the late 1970s I wrote a very concise piece
of bit-twiddling code to set VSAM options which was particularly tricky to
understand, despite detailed comments, and after finding myself rechecking it
several times over the years, I added a comment saying "This code is correct.
Do not waste time checking it. If there is a bug, it is somewhere else!".
Some years later, long after I had left that company, I received a note
thanking me for how much time that comment had saved!
Jonathan Scott
