Documentation Standards - Inline
Far and away the most important comments you will be writing in assembly will be the in-line comments. As you work, you will need to let me know what you are doing since assembly code can quickly become cryptic. For example... the following block of code with the comments removed. Try to figure out what this is doing.
call strLen add si, ax sub si, 3 mov bx, si mov cx, ax dec cx dec cx ReversingLoop: mov al, [si] mov [di], al inc di dec si loop ReversingLoop mov si, bx mov BYTE PTR [di], CR inc di mov BYTE PTR [di], LF inc di mov BYTE PTR [di], 0
... any idea? Here is the same block of code with the comments added back in.
COMMENT # PROCEDURE HEADER PURPOSE: Reverses a string passed in CALLED AS: strRev (String1, String2) DS:SI points to the string to reverse ES:DI will contain the reversed string It is assumed that DS:SI is ASCIIZ with a LF, CR, 0 terminating it. REMARKS: # call strLen ;ax will contain the length of string add si, ax sub si, 3 ;si now points to last "real" char mov bx, si ;keep a pointer to the EndOfString mov cx, ax ;keep a copy of the length of string dec cx ;this is used by the loop instr below dec cx ReversingLoop: ;This will reverse characters only mov al, [si] ;copy source from end to start mov [di], al ; into the destination from inc di ; start to end dec si loop ReversingLoop ;loops until cx = 0 mov si, bx ;points to the last real char again ;Add on a LF, CR, and NULL mov BYTE PTR [di], CR inc di mov BYTE PTR [di], LF inc di mov BYTE PTR [di], 0
Any idea what this block of code will do? As you may have guessed, it will reverse a string by copying the characters backwards. Assembly code by itself is not easy to read through - that is why it is critical that you comment your code well.Last Modified: January 26, 1999 - Barry E. Mapen