=========================================== Comments on writing and commenting LMC Code =========================================== - Ian! D. Allen - idallen@idallen.ca - www.idallen.com Here are comments on past submissions for LMC assembler assignments: - Remember the order of the five columns plus comments. Don't forget any of the columns. Don't re-order any of the columns. loc code label mnem oper comment - Label (symbol) 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 source file.) - Comments add information not already given in the line of assembler. If the line of assembler says it all, don't add a useless comment. The comment should usually tell *why*, not *how*. Here are examples of useless, unhelpful, pointless comments: *** BAD COMMENTS DO NOT DO THIS NO NO NO *** 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: *** GOOD COMMENTS *** 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. Do not use mailbox numbers. - 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: ZERO DAT 000 ; zero variable ZERO is a constant; not a variable! Anything that is a variable should not depend on an initial value. Constants must never change value. - When turning code into LMC, translate the pseudo-code you wrote - the LMC codes must match the pseudo-code that you submit. If you change the algorithm in the LMC assembler, you have to make the pseudo-code match. - Programs must work when run twice in a row. Do not expect some variables to start with an initial value and then modify the values of those variables in the program, because the next time you run the program the variables will have the wrong values in them. Always use constants to set the values of variables at program start. 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. -- | Ian! D. Allen - idallen@idallen.ca - Ottawa, Ontario, Canada | Home Page: http://idallen.com/ Contact Improv: http://contactimprov.ca/ | College professor (Free/Libre GNU+Linux) at: http://teaching.idallen.com/ | Defend digital freedom: http://eff.org/ and have fun: http://fools.ca/