of good documentation:
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:
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 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)
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:
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:
System/370 Assemble documentation hints—Do’s and Don’ts
Write statements in random columns. This makes and program very unreadable. The following is a defacto standard for S/390 assembler statements:
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.
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.
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.
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.
Merely restate an instruction when you place a comment on it. The following example illustrates this point. Which of the following is more explanatory?
Add VAR TO REGISTER 1
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.
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.
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.
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:
$ => INST. MODIFIED IN EX INSTRUCTION
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.