Path: utzoo!news-server.csri.toronto.edu!cs.utexas.edu!usc!elroy.jpl.nasa.gov!sdd.hp.com!ucsd!dog.ee.lbl.gov!ucbvax!mvs.draper.COM!seb1525
From: seb1525@mvs.draper.COM ("Stephen E. Bacher")
Newsgroups: comp.lang.asm370
Subject: Re: programming style
Message-ID: <9103050128.AA16369@ucbvax.Berkeley.EDU>
Date: 5 Mar 91 00:34:00 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Reply-To: IBM 370 Assembly Programming Discussion List
              <ASM370@OHSTVMA.BITNET>
Distribution: inet
Organization: The Internet
Lines: 65

Ready for a personal preference flame about assembler comments?

Rather than the established style of

         C     R1,FOOLOC           Is value equal to FOO?
         BNE   NOTFOO              No
         LA    R2,BAR              Yes, frobulate with BAR
         LA    R3,BAR+1            Do something else BAR-related
         B     PASTFOO             Skip rest of check
NOTFOO   DS    0H                  Value is not FOO
         LA    R2,BAZ              Frobulate with BAZ
         LA    R3,BAZ+1            Do something else BAZ-related
PASTFOO  DS    0H                  Check done

which is so prevalent among assembler hackers, why not use

         C     R1,FOOLOC           If value is equal to FOO,
         BNE   NOTFOO              then...
         LA    R2,BAR               frobulate with BAR
         LA    R3,BAR+1             do something else BAR-related
         B     PASTFOO             end
NOTFOO   DS    0H                  Else (value not equal to FOO)...
         LA    R2,BAZ               frobulate with BAZ
         LA    R3,BAZ+1             do something else BAZ-related
PASTFOO  DS    0H                  end

Doesn't this show better the REAL structure of the code you're trying
to write?  This can be extended to more complicated logic involving
multiple tests, which can be expressed in terms of AND and OR.
Here's an example from our TSO SUBMIT exit...

         EX    R4,UIDCOMP1         If jobname matches userid
         BNE   NEWJOBCH             and
         TRT   0(1,R15),JCHARTBL     the jobname character is valid
         BNZ   NEWJOBCH               then
         IC    R6,0(,R15)              use last char of input jobname
         B     NEWJOBNM            else...
NEWJOBCH DS    0H
         LA    R6,C'$'              replace with default char "$"
NEWJOBNM DS    0H                  Generate new job name

The logic is clear and readable without having to resort to additional
comment blocks.  AND, it helps the programmer code correctly.

Here's another example - a common looping construct.  This one is taken
from the "XPROC" program (a CLIST-to-REXX conversion helper) and
slightly modified for readability:

KVPPLOOP DS    0H                  Loop to check for duplicates
         C     R0,POSDLEN           If lengths don't match,
         BNE   KVPPNEXT              then continue
         L     R14,POSDADDR         Point to old parameter
         EX    R15,COMPWORD         If values are equal,
         BE    ERRORDUP              then error
KVPPNEXT LA    R2,POSDDATL(,R2)     Else continue
         BCT   R8,KVPPLOOP           until no more positionals
KVPPLEND DS    0H                  End loop to check for duplicates

I would like to see more assembler programs try this commenting style.

- SEB

P.S. Another good reason to use DS 0H instead of EQU * is that
     TSO TEST knows labels defined with DS, but doesn't know
     labels defined with EQU.