Goals: Write everything down. (Reprise)
Good programs are not only well planned and systematically written, but also are thoroughly documented. There are two major categories of documentation that must be produced if a program is to be used properly or even understood by its own writer at a later date:
A manual must be produced for the ultimate user of the program. This external documentation must explain in a clear, non-technical fashion what is expected of the user at each step, and what the program will do with the information provided. In commercial practice, a person other than the programmer usually writes the manuals in order to avoid the use of technical jargon, and orient the documentation to the user. It is best to write the user manual before coding the program, specifying completely what every screen will look like, what all the commands are and exactly what they will do. The user manual then becomes part of the specifications for writing the program. One or two sample user manuals will be given later as part of extended examples.
The program itself ought to contain carefully written documentation. This material is of three types:
The rules for constructing names were discussed in section 2.2.4. These rules apply to all names, not just to modules. It is not enough, however, to be able to construct names that follow the syntactical rules for Modula-2. Names ought also to be given creatively, so that they provide part of the program documentation, assisting the programmer to read and understand the work at a later time. Modules, variables, and other items that require names should therefore be identified descriptively. That is, a module name should reflect its function, and that of an item in the module should reflect its use or role in the program.
Poor Module Names: Snafu, Tarfu, Fubar, MyProgram, ThisCode, Thingy.
Some of these are easy or traditional, but they have no meaning in the context of the work being undertaken.
Good Module Names: Hello, ComputeInterest, FindArea, ComputePowers.
These state, imply, or at least hint at the purpose of the module they name.
Poor Variable Names: i, j, k, n, p, r, t, x, var, thing, a1, a2, a3.
Such names may be easy to type without much thought, but they produce cryptic and nearly unreadable code.
Good variable names: interest, number, principal, rate, time, side, base, exponent.
By describing their role in the program, such names immediately inform the reader of the code what is supposed to be happening when the program is run. This makes both understanding and modification feasible. There is nothing more embarrassing than being unable to understand your own code just weeks after writing it. (Except, perhaps being unable to bring out a new version of a commercial package because no one in the company understands the code.) It also illustrates that:
Programs are meant to be read by humans, not by computers.
Writing a program can be a long and tedious process. The more useful the program is expected to be, the longer and more complex the source code (text file) is likely to become. If anyone wants to change a section later, will it be possible to find out why they were written the way they were? Does the programmer even understand the beginning of the program by the time the end is reached? Can someone else read and modify the work several years later?
To ensure that there will be positive answers to these questions, all programming notations provide a mechanism for inserting explanatory notes within the original text file. These comments are ignored when the compiler reads the file, but are necessary for human beings to be able to read it intelligently. In Modula-2, comments are enclosed in comment parentheses, which consist of the reserved symbol (* to begin a comment and the reserved symbol *) to end one. Here is the current example, heavily commented:
MODULE PowersCommented; (* This is the title line. *)
(* Written by R.J. Sutcliffe *)
(* as an introductory example *)
(* and to demonstrate comments *)
(* using P1 Modula-2 for the Macintosh computer *)
(* last revision 1993 01 25 *)
(* Note that comments such as the one above ought always to be included in the source file in order to identify its writer and purpose. (* Observe that comments can extend over several lines and can include other comments. *) *)
FROM STextIO IMPORT (* comments can go here, too *)
WriteString, WriteLn;
FROM SWholeIO IMPORT
WriteCard;
(* Alternately, have in non-ISO Modula-2:
FROM InOut IMPORT
WriteString, WriteLn, WriteCard;
*)
VAR
base, exponent, counter, result: CARDINAL;
BEGIN (* The program starts here *)
(*
Introductory Section: note that a program ought
also to identify itself when run. Note too this
alternate style for multi-line comments.
*)
WriteString ("The program Powers");
WriteLn;
WriteString ("was written by R.J. Sutcliffe");
WriteLn;
WriteString ("as an introductory example");
WriteLn;
WriteString ("This program raises a base to an exponent");
WriteLn;
(* Set up the key variables *)
base := 4;
exponent := 6;
(* calculation section *)
result := base; (* initially, set the result to the base *)
counter := 1;
WHILE counter < exponent
DO
result := result * base; (* multiply base enough times *)
counter := counter + 1
END;
(* display the result *)
WriteCard (base, 0);
WriteString ( " raised to the power ");
WriteCard (exponent, 0);
WriteString (" equals ");
WriteCard (result, 0);
WriteLn;
END PowersCommented.
A comment is any material enclosed within the comment parentheses which are "(*" and "*)."
The student should observe carefully how effective comments are used in the longer and more detailed examples in this book.
The meaning of most programs of any substance will be ambiguous at times even to experienced users. At such times, it may be useful to be able to select a "help" option within the program itself, rather than have to look the information up in a printed manual. Because of space limitations, this type of documentation will not be fully illustrated in the programs in this text. However, there will be instances of on-line help in such situations as error handling. Commercial programs, however, require such documentation just to be regarded as acceptable in the modern marketplace. In such projects, on-line assistance must be planned for at each step of the program design. It should be complete, (though not so complete as the printed documents) and should be relevant to the context of the program at the time the help is requested. Apart from this remark, further comment on this point is beyond the scope of this text.