When you write subroutines think of it as creating a “black box” functional block that you may use several times in your program. Consider, too, that your program may contain dozens of subroutines, and that you may not actually write the code that calls a subroutine until several days after you write the subroutine. It therefore makes sense to include with the subroutine a brief specification of what it does.

I like to delineate the start of a new subroutine with a visual border, say a row of asterisks. I then preface the subroutine with one or more lines of comments (depending on the complexity of the subroutine) that define its function. Here is an example:

***** ValidCloseCommand ******************
; Return True if a validated close command exists.
; The condition for this is:
;  *  The manual button is pushed OR the failsafe timer has expired
;  *  AND the photo cell is not tripped
;  *  AND the pump is not operating

;Registers:
;  On entry: None
;  On exit : X contains the result
;  Stack   : Clobbers T and Z. 

;Subroutine stack:
;  2 levels (calls another subroutine)

ValidCloseCommand:
      GoSub      PumpOperating    ;Get True if yes
      NOT
      Push                        ;Make a copy
      RetIfF                      ;Testing consumes one copy
      Input      PhotoCell        ;False if tripped
      Push                        ;Make a copy
      RetIfF                      ;Testing consumes one copy
      Input      ManualButton
      Test       SomeTimer        ;True if still timing
      NOT                         ;True if timed out
      OR
      Return
*******************************************