Documentation

Home Up Search Credits Site Map Contact Info. Links Disclaimer Download

Goals of good documentation:

  1. Aid in designing good programs
  2. Aid in debugging programs
  3. Make programs clear and understandable once written
  4. Make structure of program well-organized

 Good documentation is a great aid to producing clear, well written, and understandable programs, and can save much programming and computing time.  Good documentation is especially necessary for programming projects requiring either a long period of time by one programmer, any period of time by more than one programmer, or modifications to any code by another other than the original author.  Good documentation techniques can be helpful in the following ways:

 Program Design

Many beginning programs seem to write programs in haphazard and unplanned ways, and often add comments only after the program is running.  This method not only leads to poorly-structured programs, but also usually results in wasted time, and is not feasible except for relatively trivial programs.

 A much better method is to write most of the overall comments with a flow chart first, specifying the structure and convention of the program, and then writing the program to fit.  This usually leads to cleaner-coded, well-structured programs, which are produced in less time than those written by most novice programmers.

 Program Debugging

Program debugging is aided by documenting a program before and during its creation, rather than afterward.  Many mistakes can be avoided by having programming conventions well specified before writing the code.  The very act of adding a comment to a statement often helps identify errors in the statement, because it forces the programmer to think about the function of the statement.  Finally, good documentation is useful if help is required from someone else, since it aids one in the understanding the program quickly.  (It also makes other people much more willing to look at the program)

 Program Modifications

Clear and complete documentation is absolutely invaluable with a program must be modified, especially if anyone but the original programmer is making the changes.  It may be noted that useful programs tend to be modified often.

Assembly Language Documentation

The following advantages apply to any computer language.  However, they are most important for assembly language, for the following reasons:

  1. Assembly language programs typically require many more statements than do high-level language programs for the same task.
  2. Assembly language programs are not usually self-documenting.  Without good documentation, not even the programmer who wrote the code would be able to understand it several months later.
  3. Assembly language programs are often very sensitive to minor changes, must more so than higher-level language.

The remainder of this section describes a well documents assembly programs, and notes the various techniques, which can be used to achieve these result.  Briefly, a well –documented program has the following characteristics:

  1. The documentation structure mirrors the program structure, and it leads from the general to the specific.  Thus, the program begins with a block of comments, which describes the overall purpose of the program, and gives some indication of the general structure.  Each major section has a block of comments describing it, as does each of the section’s subsets.
  2. At least 95% of machine-instruction statements have comments.
  3. The program is easy to ready, and blocked off into logical sections, so that anyone may look at it and understand it easily.
  4. Good programs typically have 15-25% of the total statements as comments.  In addition to the comments on the individual statements.

System/370 Assemble documentation hints—Do’s and Don’ts

 

Don’t

Write statements in random columns.  This makes and program very unreadable.  The following is a defacto standard for S/390 assembler statements:

            Col.            1            Labels
            Col.            10            Operation codes
            Col.            16            Operand filed(s)                      
            Col.            36            Comments (some people prefer cold 40)
            Col.            72            Continuation column
            Col.            73-80            Sequence numbers

Don’t

Place a comment card before every statement.  This is a bad habit and makes programs absolutely unreadable.  Embedded comments should be used to block programs into logical sections, not to explain the function of individual statements.

Don’t

Bury code with too many interspersed comments.  If so many comments are necessary, place then in blocks ahead of the program segments and not in the middle.

Do

Put a comment on nearly every machine instruction.  Comments are also helpful for explanation of variables and flags.  Each comment should describe the function of its statement, and generally, it alone.  If a comment is needed to describe the function of a block of half-a-dozen instructions, it probably should be placed on a comment card preceding the block of code. These comments should be coded when the programs is originally written.  Often, this result in catching may mistakes at that point.  It is noted that a few novice programmers do this, while most experts do.  It is also noted that many programmers who do this whish they had started doing so earlier, since they realize how much time they had wasted by not commenting the original program.

Do

Use TITLE, SPACE, and EJECT commands.  The command “TITLE  ‘a heading Message’  skips the listing to a new page, and prints the heading message at the top of every page till another TITLE command is issued.  This not only clearly labels your listing, but it save time in looking through a listing which is more than a few pages long.  The command “EJECT” skips the listing to a new page, and is useful in blocking off major parts of a program.  The command “SPACE N” inserts N blank lines into a listing at that point.  This is useful for blocking off smaller sections of a program.

 Don’t

Merely restate an instruction when you place a comment on it.  The following example illustrates this point.  Which of the following is more explanatory?

A            R1,VAR                      Add VAR TO REGISTER 1
A            R1,VAR                      R1=SUMMATION OF ODD PRIME NUMBERS

 Don’t

Put several single comments between statements in an unreadable manner.  It is often useful to indent a single comment to column 16.  This keeps it from interfering with the reading of labels and OPCODES, and thus distinguishes it from the machine instruction.

 Do

Use comment card blocks, which list useful information.  For example, a list of register allocation and usage is extremely helpful, not only in debugging, but also in revising a program.  Such a list should appear as part of the preface to the appropriate section of code.  Another example is a list of calling conventions fore subprograms.  Fore extensive programs, lists of the following might be kept at the beginning of each subroutine: MACROS used, subroutines called by this subroutine, subroutines which call this subroutine, variables used by this subroutine, variables changed by this subroutine, etc.

 Do

Block off large sections of comment cards in the code.  Large blocks of comments can begin in whatever column is appropriate, but in general, should use most of the card image, since they will otherwise add a great deal of length to a program.  For the sake of appearance, comments should be blocked off by blank lines (SPACE N) or lines of continuous characters.  The most common character used for this purpose is asterisks (*) (in columns 1-71, or in just the odd columns).   An esthetic appearance can be obtained by placing an asterisk in column 71 of each comment card in a major block, with lines of asterisks before and after the entire block of documentation.

 Do

Flag instructions, which will be modified during execution in order to make programming logic obvious.  This can be accomplished by using “*-*” or “$”, the latter EQU’ed to zero, for any modified field.  For example:

$         EQU               0                                          $ => INST. MODIFIED IN EX INSTRUCTION
.. .. .. .. .. .. .. other statements  .. .. .. .. ..
            STC            R2,MVC+1                           SET BUFFER LEN. FOR LATER
.. .. .. .. .. .. .. other statements  .. .. .. .. ..
MVC   MVC            OUTPUT($),0(R5)            MOVE VARIABLE # OF BYTES INTO
*                                                                            OUTPUT BUFFER

Do

Use variables equates for the registers and not just the register number.  This convention will allow you and the next person that reviews or modifies the code to see all the instructions that use a register in the cross-reference listing.  This will allow everyone to find unused registers and to identify conflicts in register usage.  The general convention is to equate R0 EQU 0, R1 EQU 1, etc. 

The above method has been derived both from the examination of many professionally written programs and from experience.  Thus, they are not arbitrary rules but techniques, which have been widely used and proven to be effective aids in programming assembler language.

Credits:  This document was a green-bar listing found from about 1972.  It appears to be from the Pennsylvania State University.

The information on this site is the combined effort of a lot of people, please credit the authors if you use their information.
Please read the Disclaimer page for the restrictions, copyright, and other uses of the information contained on this site.
For problems or questions regarding this web contact Bob.
Last updated: January 25, 2004.