On Wed, 27 Feb 91 08:22:00 EST Philip Harshman 3697 said:

Hi John and Philip,
  The history behind, why the special character, includes the following.
The MACRO assembler for DOS had a comment placement problem.  When code
was expanded, comments would float according to the variables pluged in.
The solution was to place a "special character" preceeding the comment.
This made the comments align properly. If you look at some old IBM code
you'll see a "." in front of some generated code.
  Now on to my personal preferance.  I don't use a special character
in front of my comments.  I do, however, have another ideosyncracy.
When the code is to branch somewhere I comment it with a ">".
e.i.
*--------------------------------------------------------------------*
*        R O U T I N E   T O   D O   S O M T H I N G                 *
*--------------------------------------------------------------------*
ROUTINE  EQU   *
         LA    R2,45           SET REG.2 TO 45.
         LA    R3,TABLE        POINT REG.3 TO TABLE.
LOOP     EQU   *
         CLI   0(R3),X'FF'     CHECK FOR END OF TABLE.
         BE    ENDROUT         >YES, BRANCH.
         ...
         LA    R3,8(,R3)       BUMP TO NEXT TABLE ENTRY.
         BCT   R2,LOOP         >GO LOOP UNTIL DONE.
ENDROUT  EQU   *

  We all have personal preferances in the way we code, of course I think
my code is the best and only way to code assembler.  Which losely
translates to don't try to teach this old dog any new tricks, I hate
change.

Enough for now,

Steve

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.

  I have no real objections to this indented comment style.  But if you
were writing code that I had to maintain I would tell you not to waste
too much time with the pretty printing of it.

  The fact is, if I have to look at the code closely enough to need to
know the structuring, I'm probably not going to pay much attention to
the comments at all.  It is what is to the left of the comments that
really tells you what is happening, and when push comes to shove that is
what you must rely on.

--
=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=

  Northern Illinois Univ.
  DeKalb, IL 60115                                   +1-815-753-6940

Yep.  I was once reading JES2 source, trying to determine whether
something was a feature or a bug.  I came to one line where the
comment seemed to conflict with the instruction.  After staring at it
for an hour, I called the support center.  The level 2 person checked
into it and discovered that the comment was backwards.  They wouldn't
take an APAR to fix the comment, but said they'd "leave a note on the
board for someone to fix that comment the next time that area was
touched."  Sigh.

/Leonard

I believe that this is a limitation of the assembler, which won't
produce "TESTRAN cards" (SYM records) for equates.  The SLAC mods
address this issue.

$ disclaim                David Andrews   tarpit!bilver!dandrews
NOTHING HAPPENS

I believe that this is a limitation of the assembler, which won't
produce "TESTRAN cards" (SYM records) for equates.  The SLAC mods
address this issue.

$ disclaim                David Andrews   tarpit!bilver!dandrews
NOTHING HAPPENS

I prefer neither DS 0H nor EQU *.  Since I frequently resort to using XPEDITER
to debug, and the latest version of XPEDITER doesn't recognize labels on
either DS 0H or EQU * lines, I use ANOP's.  Of course that wastes a little
space, but what they hey?

+----------------------------------------------------------------------------+
+ Adam Goldberg                         H:(515)233-5135                      +

+ "It's simple!  Even a Pascal programmer could do it!"                      +
+----------------------------------------------------------------------------+

        Andrews) writes:

I prefer neither DS 0H nor EQU *.  Since I frequently resort to using XPEDITER
to debug, and the latest version of XPEDITER doesn't recognize labels on
either DS 0H or EQU * lines, I use ANOP's.  Of course that wastes a little
space, but what they hey?

+----------------------------------------------------------------------------+
+ Adam Goldberg                         H:(515)233-5135                      +

+ "It's simple!  Even a Pascal programmer could do it!"                      +
+----------------------------------------------------------------------------+