Assembly Language Comments

Subprogram comments

As in high level language programs, the most important comments in an assembly language program are subprogram comments. These comments should Subprogram comments should be put in when you begin writing code. Most students spend more time debugging code than writing it. When you are debugging code, you will need to read through your code to try to find out what you are doing wrong. That is difficult and prone to error without comments that indicate how subprograms are called. The time you are saving by not putting in the comments gets paid back, probably many times over.

Algorithm comments

It is not necessary to comment every line. When three or four lines of code work together to accomplish some higher level task, it is better to have a single higher level comment for the group of lines.

With this kind of commenting, you can engage in two kinds of thinking when you are debugging. By looking at your comments, you can check the correctness of the algorithm. Then if the algorithm is correct, you can look at code and compare it to the comments - does the code do what the comment says? This kind of debugging only requires checking assembly language for short segments of code. The rest of the time you are thinking in terms of a higher level algorithm.

Register usage comments

Another kind of helpful commenting is comments describing how a register is used. If a register is used for a single purpose within a subprogram it is useful to describe it and to give it a meaningful name, and use that name in your comments in the body of the code. Otherwise the algorithm comments look like: 
# Here are some useless comments.
	lb	$t3, ($t0)	# load $t3
	sb	$t3, ($t1)	# store contents of $t3
	sub	$t2, $t2, 1	# decrement $t2
	add	$t0, $t0, 1	# increment $t0
	add	$t1, $t1, 1	# increment $t1
These comments do not help anyone with a minimal knowledge of assembly language. They certainly will not help you to read your own code.

The following comments are better; they get across a higher level view of what is happening: 

# Register usage:
#
#	$t0 (ptr1)	- pointer into str1
#	$t1 (ptr1)	- pointer into str2
#	$t2 (numLeft)	- number of characters left to be copied
#	$t3 (temp)	- temporary register for character move
#
	lb	$t3, ($t0)	# copy a character from *ptr1 to *ptr2
	sb	$t3, ($t1)
	sub	$t2, $t2, 1	# decrement numLeft
	add	$t0, $t0, 1	# advance ptr1 and ptr2
	add	$t1, $t1, 1

Page URL: http://www.d.umn.edu/~gshute/spimsal/comments.html
Page Author: Gary Shute
Last Modified: Saturday, 24-Mar-2012 10:08:45 CDT
Comments to: gshute@d.umn.edu