Software Design Using C++C++ Formatting and DocumentationFormattingAlthough a program should first of all meet its specifications, there are important considerations other than correctness. 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 +. Indenting properly can do much to improve the ease of reading a program. It is typical to indent the "loop body" of a loop by about 3 spaces. Similarly, one should indent the body of a function about 3 spaces as well as the choices inside of an if/else. Look at the short example below as a guide. DocumentationIf 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. This section of documentation is essentially a brief user manual. A stranger who reads this section should know what your program does as well as how to set it up and run it. The documentation at the top of a program file should list the date, the name of the author, the names of any other people who contributed to it, and any references used in any significant way (books, web sites, etc.). This allows both you and others to know at a glance what sources were used in producing this program. Internal documentation 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.) The Given/Task/Return style of function comments is suggested. In this, the "Given" section lists each parameter that is used to send a value into the function. Beside the name of the parameter, a description of its meaning is listed. The "Task" section describes the overall task of this function. It tells the reader what this function does if the function is called. Always describe the task in terms of the parameters. Try NOT to use items outside of the function in this description. The "Return" section lists each parameter (and its meaning) that is used to send a value back out of the function. It also lists any value returned in the function name and its meaning. 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 diagrams, a record of testing, etc. Example
Other ConcernsEfficiency 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 you 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
Related Items |