What's in a name? "A rose is a rose is a . . . ." "There's more form than substance." Perhaps these sentiments are true, but in a well-presented program there is a great deal in a name. One function is not another function, and understanding of substance is enhanced by form.
Indentation and proper spacing serve to delineate significant components of a program. Choosing names to convey and delineate purpose is also extremely important. Even without the descriptions given for the functions of Figure 1.3, the names of each function, variable, and constant almost provide, by themselves, enough information to see what each does. On the other hand, inappropriate names can be very misleading and distracting.
Reading identifiers to understand what a program does requires reading the entire program. This is too demanding. After all, when selecting a book, no one wants to be forced to read from cover to cover just to see what it is about. The same holds for a program, program documentation must be provided for this purpose. Good name selection is not enough. The main program and each of its functions must start with comments that allow users (including its author) to understand readily what it does and what its inputs, outputs, and parameters are. The main program's documentation then tells immediately what it does. No further reading is necessary unless someone wants to know how it is done. Similar comments can precede program segments that implement tasks of some complexity. To a great extent, the structure of a function, coupled with the documentation of each of its tasks, explains how the function does what it does. In this sense, structured programs (with proper comments) are self-documenting. Functional modularization and data abstraction help to elucidate structure by obscuring detail. Some programmers are free to develop their own style for delineation and documentation; for others it may be specified rigidly. The case study presented later gives a complete program with documentation as a guide for annotating your own programs. As a rule, complete documentation is not included in programs appearing in this book, since in effect the text itself serves as documentation, discussing completely each program presented. Still, programs will be annotated for clarity. Proper documentation is a prominent aspect of every good program and should become a habit of the programmer. Since the top-down approach requires a description for each task, the documentation for a task may be done as it is introduced, even before it is written.