Comments are or, better, should be of two sorts:
1) Substantial prefixed blocks of text, often several hundred lines of
them, that describe what will be done and how it will be done, and
explicate coding conventions for parameters, and
2) comments following single instructions, 'remarks'.
For concreteness, I have copied some comments of both kinds from a
macro writtren several years ago that I was working on---to add
UNICODE support to it--yesterday.
Spacing becomes erratic when code is copied into email text; but the
result, while ugly, does illustrate what I take to be good practices.
Example of 1)
.*
.* The decimal capacities of the four extension-element sizes that are
.* supported here are shown in the text table below.
.*
.* +----------------+----------------------+----------------------+
.* | byte size | minimum | maximum |
.* +----------------+----------------------+----------------------+
.* | 1, byte | -128 | +127 |
.* | 2, halfword | -32768 | 32767 |
.* | 4, fullword | -2147483648 | +2147483647 |
.* | 8, doubleword | -9223372036854775808 | +9223372036854775807 |
.* +----------------+----------------------+----------------------+
.*
.* It is worth reminding readers that storage representation is what
.* is being discussed here. Their twos-complement register represen-
.* tations are all eight-byte ones. (Those who prize the antique may
.* wish to think about four-byte representations of the first three
.* too.)
.*
.* TXs are not themselves usually ordered; and their elements com-
.* prise a multiset, the elements of which need not be unique, rather
.* than a set, the elements of which must be unique.
.*
.* It is possible to generate a TX in line, as a part of of a contain-
.* ing table RSECT or as a separate RSECT.
.*
.* To generate an in-line TX
.*
.* o supply a value of the &txlabel positional parameter;
.*
.* o do not supply a value of the tabname= keyword parameter; and
.*
.* o code RSECT=no explicitly.
.*
.* To generate a separate TX RSECT instead
.*
.* o do not supply a value of the &txlabel positional parameter;
.*
.* o supply a value of the RSECT= keyword parameter; and
.*
.* o default to or code RSECT=yes
.*
.*
.* coding
.*
.* The coding conventions for this macro's parameters are discussed
.* seriatim below.
.*
.* The value of the &txlabel positional
.* &txlabel parameter must be a licit HLASM
.* label, one having the left-recursive
.* BNF syntax of
.*
.* <internal label> ::= <internal label><licit non-initial character>
.* | <licit initial character>
.* <licit initial character> ::= <majuscule> | <minuscule>
.* | <extender>
.* <majuscule> ::= A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S
.* |T|U|V|W|X|Y|Z ^
.* <minuscule> ::= a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p|q|r|s
.* |t|u|v|w|x|y|z ^
.* <extender> ::= @ | # | $ | _ ^
.* <licit non-initial character> ::= <licit initial character>
.* | <numeric>
.* <numeric> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 ^
.*
.* Additionally, no internal-label value may be more that 63 charac-
.* ters in length (after any editing operations that remove framing
.* single quotes and/or any leading and/or trailing blanks).
.*
.* Some examples of licit internal labels are
.*
.* ADDT_LABEL03 Gubbins __2q3A__
.* column_7_addt array_addt_column6 $label_TX2
.* ElementEsSubscriptArray CIDT_minima
.*
.*
Example of 2)
.*---------------------------------------------------------------------
.*
.*
.* RSECT= checks
.*
.*---------------------------------------------------------------------
|&RSECT_available setb 0 --ex hypothesii
|&in setb (t'&RSECT ne 'O') --value supplied?
| aif (&in).RSECT_in --if so, examine it
|&abort setb 1 --no, set quit switch
| mnote &el,'&mnpfx.000i. A value of the RSECT= keyword paramet*
| er must by but has not been provided. Supply one. Note*
| , moreover, that this error is an aggravated one. The d*
| efault value, RSECT=yes, was nulled out without replacem*
| ent, thus ensuring that the expansion of this &macname m*
| acro instruction would be aborted.'
| ago .after_RSECT
|.RSECT_in anop
|&rstemp setc DEQUOTE('&RSECT') --strip any framing single quotes
. . .
The important point about comments of this second sort is that they
should motivate, not describe. A comment like 'store registers'
attached to an SR instruction is worse than useless. Also worth
noting explicitly is that mnote text---It traditionally has been but
need not be so terse as to be all but unintelligible--has the
secondary use of making clear how errors are handled.
Finally, let me make one more general comment. Rules, in particular
rules that require that some specified fraction of the lines in a
routine be commented, are of no use. They are indeed
counter-productive. They are sometimes complied with, but the quality
of the comments they elicit is abysmal.
There are no bureaucratic solutions. Good commenting practices can
be illustrated and encouraged. Editing of the sort that MSS receive
can be helpful. Attempts to have the programming police enforce them
are always counter-productive.
John Gilmore, Ashland, MA 01721 - USA
