Hardware Reference
In-Depth Information
Improved case converter subroutine (self-documenting)
; LOWER TO UPPER CASE CHARACTER CONVERSION
; PARAMETERS PASSED:
; ENTRY: AL=ASCII character (upper or lower case)
; EXIT: AL=ASCII character (upper case only)
; REGISTERS: AL, F
;
upcase:
CMP
AL,'a'
;
Is it already upper case?
JL
exit
;
If so, do nothing
CMP
AL, 'z'
;
Or is it punctuation?
JG
exit
;
If so, do nothing
SUB
AL, 'a'-'A' ;
Otherwise, change case
exit:
RET
The second example shows how a program module can be made largely
self-documenting by the inclusion of effective comments and a meaningful
header. Note that the name of the routine has been changed so that it is easier to
remember and is less likely to be confused with others. Finally, the code itself
has been modified so that its action is much easier to understand.
Documentation is particularly important where software development is
being carried out by several members of a team. Each development phase
will rely on the documentation prepared in earlier stages, hence documentation
should be considered an ongoing task and a folder should be prepared to contain
the following items:
•
A
detailed
program
specification
(including
any
notes
relevant
to
the
particular hardware configuration required).
•
Flowcharts or descriptions of the program written in structured English.
•
Lists of all definitions and variable names.
•
Details of macro or sub-routine libraries used.
•
Details of memory usage (where appropriate).
•
A fully commented listing of the program (latest version).
•
A diary giving the dates at which noteworthy modifications are made together
with details of the changes incorporated and the name of the programmer
responsible.
•
A test specification for the program with descriptions and results of diagnostic
checks performed.
Presentation
Finally, attention should be given to the way in which the program interacts
with the user and the aim should be that of making the software as 'user-
friendly' as possible. Prompts and messages should always be meaningful and,
whenever any doubt may exist, the user should be prompted with the range
of acceptable values or valid responses and
help screens
should be provided
wherever appropriate. Later chapters provide further examples of programs
presented in different formats.
