Comments in Assembly Programs

Comments are extremely important in your Assembly programs. They will help you remember what the code does when you look at it at the end of the semester or next year. Good engineers always plan ahead. Start now by commenting your code correctly. This section brings you general guidelines for properly commenting your assembly programs.

General Program Comments

Below are some examples of properly and improperly commented code:

Bad Commenting

	ORG 	$C000
ADR1	EQU	$c100	* ADR1 equals $c100
ADR2	EQU	$c200	* ADR2 equals $c200
	LDX	#ADR1   * load X
	LDY	#ADR2   * load Y
LOOP	LDAA	$0,X    * load A
	STAA	$0,Y	* store A
	INY		* inc Y
	INX		* inc X
	CPX	#ADR2	* compare X
	BNE	LOOP	* branch LOOP
	SWI		* software int.
	END

Good Commenting

***************************************************************
** Program to copy 255 bytes from $c100 to $c200
**
** By: John J. Smith
** January 1, 2000
***************************************************************
**
** Data Definitions:
**
	ORG	$C000
SOURCE	EQU	$C100	  * Source of data to copy
TARGET	EQU	$C200     * Destination of data to copy
**
** Program Code:
**
        LDX     #SOURCE   * load X with source address
        LDY     #TARGET   * load Y with target address
LOOP    LDAA    $0,X      * get a byte from source memory
        STAA    $0,Y      * store the byte in target memory
        INY               * X points to the next source byte
        INX               * Y points to the next target byte
        CPX     #TARGET   * Test to check if we're done
        BNE     LOOP      * IF: not done, get another byte
        SWI               * ELSE: terminate program
        END
****************************************************************

Notice that properly commented programs include a header describing author and creation dates, and much more information. It is also a good place to keep version information. Also, note how the labels used are more descriptive and how the comments actually describe what the algorithm does. A program following this format will be much easier to read and understand after you've slept for the whole summer!

Commenting Subroutines

Commenting subroutines is probably one of the most important parts you can do in all your programs. Why is it so important? The answer is simple: subroutines can be used in any program. Therefore, it is necessary to document them well. You should always document the following characteristics of your subroutines:

1. What the subroutine does
2. Which registers get modified by the subroutine
3. How to pass in necessary data (if any)
4. How results (if any) are returned
5. Labels used within the subroutine

Below is a properly commented subroutine. Notice that it could be copied into any program with no changes whatsoever. You must keep in mind the labels used in each subroutine so that you don't duplicate labels when you copy your subroutine into another program.

****************************************************************
** PageCopy - Copies up to 256 bytes from one location to another.
**
**   Registers Destroyed: A, B, X, Y
**   Pass-In Values: X holds source address, 
**                   Y holds target address
**                   A holds number of bytes to copy
**   Return Value: none
**   Labels Used:  PageCopy
****************************************************************
**
PageCopy:
	LDAB	$0,X		* Load a Source byte
	STAB	$0,Y		* Store at target location
	INX			* Advance source pointer
	INY			* Advance target pointer
	DECA			* Decrement counter
	BNE	PageCopy	* Loop back if not done
        RTS
****************************************************************

ORG Statement

Another important issue is the proper use of the ORG statement. You have already learned by now what the ORG statement is. The following program will return an error if you attempt to "g c000".

         ORG     $C000
  NUM1   FCB     $00
  NUM2   FCB     $02
  RES    RMB     2
         LDAA    NUM1
         LDAB    NUM2
         MUL
         STD     RES
         SWI

Why? Because when you jump to c000, it assumes that your program starts at that address. It does not skip the data section and jumps to the program section. It will try to execute something, assuming that the bytes n the data section is the program itself. Therefore, You have to separate your data from your program. The following is the right programming style:

        ORG      $C000	* Data section
  NUM1  FCB      $00
  NUM2  FCB      $02
  RES   RMB      2

        ORG      $C100	* Program Start
        LDAA     NUM1	* ...
        LDAB     NUM2	* ...
        MUL
        STD      RES	* ...
        ...      ...	* ...
        SWI		* Program End

Copyright © 2002 Vanderbilt University