Software Design Using C++

A Matter of Style: The Art of Programming

Although a program should first of all meet its specifications, there are important considerations other than correctness. Many of these can be grouped under the heading of style.

Sometimes a beginning programmer has the impression that one simply sits down and types in a program. This may work for simple problems, but is a formula for disaster in anything of significant complexity. Good software is designed, engineered, crafted. This includes the use of appropriate classes, data structures, cohesive functions, etc. More will be said on these topics elsewhere.

Programs are written not just to be run, but also for others to read. Pity the poor maintenance program who is going to have to read and decipher your work several years from now! Make this person's job easier through good use of indentation, spacing, descriptive identifiers, and general neatness. It is typical, for example, to vertically align opening and closing braces, although there are a few authors who do not do this. One also should put blank lines between major sections of the program, such as between functions. It also helps a lot to put spaces after most types of punctuation, such as commas, and on both sides of binary operators, such as +. Look at the program examples in these Web pages to see examples of how to indent. Indenting properly can do much to improve the ease of reading a program.

If you provide good documentation, that maintenance programmer is going to bless you, not curse you! There is both internal and external documentation. The internal documentation is contained within the program file(s) and includes a description at the top giving the inputs, overall processing, and outputs of the program. It also includes a comment section for each function, listing what is being passed into it via the parameters, what the function's main task is, and what values are being passed back out via the parameters or function name. (For object-oriented programming, the implicit object is also used to send values in and out.) Internal documentation also includes a description of each user-defined class. External documentation is separate from the program and may consist of items like the specifications, various charts, a record of testing, etc.

Efficiency is also of some importance. Don't needlessly waste computer time or memory space. In particular, don't waste a lot of it. If there is a tradeoff between efficiency and a clear design, having a clear design is probably better (unless we would waste a lot of time or space to get it). Of course, it also does not make sense to waste a lot of your own time (or your employer's) to make minor speed improvements to a program that will be rarely used and runs fast enough as is.

Here are some "thou shalt not" rules of thumb: Don't use an obscure method when clear methods are available. Do not have a variable do double duty, as in using a variable called Total to hold both the total of some data items, and later the average of these data items. (The name Total indicates that it should hold a sum, not an average. Don't confuse the readers of your program!) Do not have a section of program do double duty in a non-obvious way. The intention of each section of code should be reasonably clear.

Related Items: