A fun thread.
Bob Bridges wrote, in part:
>1) long-winded variable names
I used to write almost exclusively in assembler, before long variable names, so
I’ve found this one hard to break—but it’s definitely a good idea.
I tend to cluster labels as much as possible: that is, in routine Banana, I’ll
use labels BananaStart, BananaTop, and the like. (OK, I’m pretending that I use
long labels here—more like BANANAST, BANANATP, etc., but I’m workin’ on it.)
This helps avoid surprises at assembly time when some other fruit gets involved
elsewhere in the program later.
>2) comment your work...I'm more likely to use one-line comments on every other
>line and a paragraph at the head of each section.
I learned this the hard way almost 40 years ago. Back at UofW, we ran a local
CMS mod on VM/SP for a couple of months over the summer, when usage was light
and we could afford the cycles. It logged the name of every command run off the
system Y-disk. Then we would look at that data (early analytics!) and look for
candidates to move into the nucleus (shared memory).
One afternoon I was looking at a local CP mod we had that would let an
unprivileged user get several bits of info about another logged on user all at
once as a set of bitflags, instead of having to issue and parse multiple
commands. I wrote a bit of assembler to exercise it. No comments—not even
register equates—since it was just a quick&dirty little program. Then I added a
few bells and whistles. Then a few more…
You can guess where this is going: that module got put on the system disk
because someone else found it useful, and the next year when we ran our
analysis, it was the most heavily used local bit of code on the system. By this
point it was over 2KLOC. Still no comments, no register equates. Yes, that’s
the point when I decided I’d better change jobs :)
I have been religious about comments since then. As Charles notes, there’s a
skill to commenting. I’ve found way too many experienced programmers who can’t
seem to grok this, and who say “There’s no point in commenting every line, it’s
obvious what it does”. They’re missing the point: the question isn’t WHAT it
does, it’s WHY. That SR R2,R2 is clearing R2; we get that, and you’re right, it
isn’t worth noting. WHY is it doing it? “Clear MVCL input length”, “Tell XYZ no
florks are available”, are meaningful and useful.
The z/VM source code is an example of commenting done right. The ratio of code
to comments is probably below 1.0. This is a good thing.
Gil added:
> An account of how it does
>what it does can also be useful, but that tends not to
>change when the program itself does.
I’ve seen this argument against commenting *at all*. I don’t buy it: not
updating the comments means you’re only doing part of the job. If you change
how it operates, you HAVE to fix the comments as part of that.
>3) Don't assume system commands will work correctly
Also theological purity, absolutely critical. I’ve long said:
Application programmers worry about how it will work.
System programmers worry about how it will fail.
Corollary: don’t deliberately hide errors unless you also check them. In CMS,
an unknown command returns a negative return code. I spent several days on a
weird customer problem back at Sterling that I eventually diagnosed as a Rexx
program that someone had put TRACE O in for no reason. If they’d left it alone
as TRACE N, the unknown command that “couldn’t” fail would have been traced.
Even better, of course, would have been if the code explicitly checked for that
failure, but this example counts as someone deliberately suppressing useful
information. Don’t be that guy (gal).
>4) Allow arguments in any order
Indeed. Positionals with meaning of course make sense in some cases, but *ix
always irritates me that you can’t put the ‑whatever option after unflagged
positional arguments.
>5) Consistent indentation
Don’t get me started…! On CMS, REXXFORM XEDIT is invaluable for indenting Rexx
consistently. Nobody has ever converted it to work in ISPF, which is a shame.
If someone’s interested, I’ll happily help; my ISPF macro skills are not up to
the task, I’m afraid. REXXFORM not only indents, but (unsurprisingly) finds
many basic syntax errors in the process, so it often saves debugging time as
well.
I’ve not done much Python programming, but the fact that indention is embedded
in the language structure is interesting.
OK, new items:
6) When you make changes to a program, ALWAYS examine the delta by hand. This
is easier in CMS, where you’ll use XEDIT in update mode and can thus look at
the resulting update deck, but compare utilities and source control systems
provide this as well. Yet I see folks not doing it in too many cases, so some
debugging display winds up getting committed, etc. Obvious exception: complete
refactor (when did “rewrite” become “refactor”, and why?).
7) (I expect pushback on this one)
Also learned from VM (and done to some extent in z/OS): name modules and entry
points with a common prefix. This minimizes collisions and makes it clearer
what’s doing what. If module ABCXYZ ABENDs, and you know that prefix ABC means
program ABC, then you’re already ahead of the game, vs. having to figure out
what program the FETCH module is part of. People claim that naming modules with
“more descriptive names” is somehow magic; if they contain ONE function, maybe.
Otherwise, the name is as likely to be confusing as helpful in my experience.
CP contains a few thousand modules, with six-character names and
three-character prefixes. Those three trailing characters can and do contain a
lot of information, and the fact that HCPFRCVM is an entry point in HCPFRC
means that when you want to look at HCPFRCVM, you don’t have to first search
the source tree to find the code. It also means that all messages from HCPFRC
are prefixed with that string, so, again, you know a lot before you even start.
I cannot (and don’t care to) think about the time I’ve wasted grepping for
function names or header file definitions in source code because people did not
follow this simple, basic rule. Yes, it also means that DSECT or header files
use a naming scheme, as do the entries in them: the HCPFRCBK defines the FRCBK,
and the variables in it all start with FRC. Rigor, rigor, rigor. It saves
lives.*
...phsiii
*You save enough time across multiple people, you’ve net saved a life.
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [email protected] with the message: INFO IBM-MAIN
