===========================================
Comments on writing and commenting LMC Code
===========================================
- Ian! D. Allen - idallen@idallen.ca - www.idallen.com

Here are comments on past submissions for LMC projects:

- Remember the order of the five columns plus comments.
  Don't forget any of the columns.
  Don't re-order any of the columns.

- Label names are similar to C/Java variable names:
  Labels can't have blanks in them.
  Labels can't start with digits.
  Labels can't have mathematics in them (e.g. no END-IF, unless you
  really mean to subtract the label at "IF" from the label at "END").
  (Some of Alan's notes show valid label math, e.g. "Dble-1".)
  Every label you use as an operand needs to appear in your code on
  the left as an address.  Every label must have an address.
  You can't have two labels with the same name in the same program.
  Two labels can have the same address; however, two addresses
  can't have the same label.
  (You can have private labels with the same name in different object
  files, but not all in the same program file.)

- Comments add information not already given in the line of assembler.

  Here are examples of useless, unhelpful, pointless comments:

      LDA one    ; load one into calculator
      SKN        ; if negative, skip next instruction by incrementing counter
      SUB INT32  ; subtract the constant 32 in mailbox 43 from the calculator
      JMP LOOP   ; jump to location zero

  The above comments are not helpful.  Don't write comments like that.
  Here are some possible better comments that provide useful information:

      LDA one    ; prepare to convert to twos complement
      SKN        ; exit (skip out of) loop when index reaches MAX
      SUB INT32  ; convert from lower-case to upper-case ASCII (0x20)
      JMP LOOP   ; repeat WHILE loop

  Comments should not reference mailbox locations, since only the
  assembler knows where things will end up in memory.  We have labels so
  that we don't need to know where things are in memory; use the labels
  in your comments.

- Using the DAT pseudo-op in assembly language:

  Use DAT in assembly language to indicate some data you want to put in
  memory.  The word DAT goes in the mnemonic operation (opcode) field. 
  The data to be placed in memory is the operand to DAT,  e.g.

     loc  code   label   mnem   oper  comment
      34   005   FIVE    DAT    005   # constant 5
      45   001   ONE     DAT    001   # constant 1
      67   000   ZERO    DAT    000   # constant 0
      82   000   PROD    DAT    ?     # variable to accumulate product
      93   000   ANSWR   DAT    ?     # variable to hold answer

  DAT and ORG are "pseudo-opcodes".  They are not executable.

- Some things are constants and some are variables.  Don't do this:

      73   000   ZERO    DAT    000   # zero variable

  ZERO is a constant; not a variable!

- When turning code into LMC, translate the pseudo-code you wrote - the
  LMC codes must match the pseudo-code that you submit.

- Some programs didn't work when run twice, because they had modified
  the values of some variables and did not reset these variables to
  the expected values when they started over.  Programs must work more
  than once (i.e. RESET, GO; RESET, GO; RESET, GO, etc.).

- When an assembler assignment asks for the mnemonic version of your
  program, that means the non-code parts; that is, four columns:
  the labels, the mnemonic opcodes, the operands, and your comments.
  "Mnemonic version" does not mean "just the opcode mnemonics".

  For LMC assignments, to the left of the the labels column, you usually
  supply two other columns: the mailbox addresses (locations) and your
  hand-assembled machine codes, just as we have been doing in class.
  Real-world assembler programs generate exactly this format.

- Pay close attention to submitting readable project listings.
  Write your code so that it fits on the screen without having lines
  fold or wrap past 80 columns.  Don't submit programs that look this:

      00  MAIN    IN                 # start of main program - inpu
   t first number into memory
      01          STO    X
      02          LDA    X           # first IF statement - compare
   first number with built-in constant
      03          SUB    Y

  Shorten your comments so that lines do not exceed the 80-column screen width.
  If you need more space, put the comments on separate lines by themselves.

  Do not submit programs with wrapped or folded lines.