Documentation Standards - Procedures
Each procedure that you hand in should contain a block comment at the top of it that gives a brief description of what the procedure does. Typically, this block should be 1-2 sentences in length, but use your judgement. Additionally, you should have a list of preconditions, post-conditions, and any remarks about the procedure. Possible remarks include all registers are returned to their original states, registers ax, bx, ... are modified, or a list of error codes if an error code is returned. A good post-condition would be the carry flag being set if an error occured. What goes where is not too critical - but be consistant. A few examples of program level comments are given below. Please note that the
TITLE killTime.ASM ;======================================================================= ; killTime is a function designed to waste a large amount of time ;======================================================================= ; PreCond -- None ; PostCond -- This task will run indefinately ; Remarks -- All registers are returned to their original states. ;======================================================================= TITLE chgPtry.ASM ;======================================================================= ; changePriority toggle between MIDDLE and HIGHEST priority ; LOWEST priority is reserved for the dummy task ;======================================================================= ; PreCond -- AL = taskID to modify ; PostCond -- The task's priority is modified ; Remarks -- All registers are returned to their original states. ;=======================================================================
Other possible comment blocks are shown below. (You can choose how you want to comment your code, but your method should be consistant, quick to do, and most importantly, readable).
;======================================================================= ; QPtChrs will write a character n times to the screen at the current ; cursor location (This code has been minimized for the TTT proj) ;======================================================================= ; PreCond -- AH=number of times to print the character ; AL=Character to print ; PostCond -- The character will be printed AH times to teh screen ; starting at the current cursor position ; NOTE: the cursor will not be advanced!!! ;======================================================================= ; Saves | Uses | Modifies ;----------------------------------------------------------------------- ; CX, BX | AX, BX, CX | AX, BX, CX ;======================================================================= COMMENT # PROCEDURE HEADER PURPOSE: Writes the ASCIIZ string to STDOUT CALLED AS: strOut (String) where String is a null terminated string (ASCIIZ) pointed to by DS:SI and the handle is on the top of the stack. REMARKS: strLen.INC must be included for this to work If an error occurs, the carry flag will be set and AX will contain the error code otherwise # AX will contain the number of characters written
Reminder: when printing source code, please use Courier or some other fixed width font.Last Modified: January 26, 1999 - Barry E. Mapen