C++ Programming Guidelines

The C++ programming language allows extreme flexibility in the design of programs as far as style and layout of program text is concerned. However, just because a program compiles and behaves correctly does not mean it will necessarily get an `A' in this course. A number of style guidelines should be followed by students in order to produce programs which are easy to read. By following these procedures, your programs will be cleaner, simpler, easier to debug, nicer to look at, and more likely to run correctly. You will find that by adopting these habits the process of writing programs for this course and beyond will be a much more enjoyable and much less tedious task. This document is by no means a complete list of all aspects of good programming style, however, and other style issues will be pointed out to you as the course progresses.

Remember that you are writing programs for others to read. When in doubt about how to organize a piece of code, always try and use the most intuitive format. You are not trying to write a super-compact piece of code, but to show that you understand the principles of program and data structure design being taught in the course. It is not the grader's responsibility to decipher your code; it is your responsibility to make your code so readable that the grader can't help but see how correct it is.

1. Commenting

(1) All files that you turn in should have a comment at the top of the file which states your name, user id, and section. This comment must also give a simple, general description of the purpose of the file.

(2) Virtually all subroutines need to have a comment describing their purpose. This comment should say what the routine expects in its input and what the result of executing it will be. Only if a procedure is extremely simple and its purpose obvious may this comment be omitted. In most cases this comment need not be long, but for some routines you may want to include a brief description of the strategy the procedure uses for solving a problem. One sample format for these comments is as follows:

//
// INSERTNAME:The given "list" is assumed to be in sorted (alphabetical)
//   order.  InsertName traverses the "list" and inserts "name" into the 
//   appropriate place in the list using the insertion sort algorithm
//   EVEN if name is already there. (In that case there will be now
//   be two copies of "name".)  The routine creates new storage to hold
//   "name". Returns 0 if successful and -1 if it can't allocate storage.
//



int insertName(Llist list, char* name)
{
    ...
    ...
}

(3) Any portion of code which uses a strange algorithm, or is otherwise non-obvious, requires a brief comment describing that code. This may take the form of either an inline comment (i.e. where the ``//'' comment form is used at the end of a line) or as a seperate line or two of description.

(4) It is often useful at the beginning of large loops to specify what is guaranteed to be true at the start of each iteration through the loop. This is also important to help YOU understand why YOUR code is working properly.

Hint: Imagine yourself trying to read and modify the code a year from now.

2. Indentation Style

The most important thing to remember about your indentation style is to be consistent. Use the same style throughout a program and use identical indentation for similar C++ constructs.

There is no one correct indentation style. Here are two popular formats we suggest.

Style 1:

while (expression) {
   ...
   ...
}

Style 2:

while (expression)
{
   ...
   ...
}

The ``...'' represents where the code to be executed gets placed. Note that both styles can be used with all of the other C++ constructs like for, if, and do-while in a similar manner.

In general, use tab stops of two to four characters. This leads to clearly identifiable indentations and does not run your code off the page too fast. You may wish to use an Electric-C package in your text editor to help indent your code as you are entering it. This package will also help check for mismatched parenthesis or braces. See your editor's documentation for further information.

3. General Guidelines

(1) Do not use any ``obscure'' C++ features, such as compiler-dependent features, operating-system features, or antique constructs.

(2) Variable names should be descriptive. If you choose appropriate names for variables, you may not need to comment their purpose. Some hints:

• Use either appropriate capitalization or use the underscore to enhance the readability of variable names, e.g. use TokenList or token_list instead of tokenlist, tlist, tl, etc. Note: You should never begin a variable or function name with an underscore. Names beginning with underscores are reserved for special operating-system and programming-package usage. (Its not actually illegal C++ for you to do this, its just asking for trouble someday...)

• We suggest using initial caps for type names (i.e., classes and typedefs). Using lower case for functions and variables, and all caps for constants (i.e., consts and #defines). When function or variable names would be written with underscores in c, we suggest capitalizing the individual components except the first. For example, the_word becomes theWord.

• Do not use variable names like i, j, or k, unless they are for counters, dummy variables, or temporary storage. If you define a global variable named i, j, or k, the graders have been instructed to burn your homework on sight.

• Do not use cryptic abbreviations in variable names. Do not use numbers to distinguish variables (for example, don't have x1, x2, and x3 and expect the grader to know the difference). A possible exception is in geometric algorithms (for example, representing a square by its corners (x1,y1) and (x2,y2)).

(3) Procedure names follow the same guidelines as variable names.

(4) Use either const or the #define pre-processor command to define constants and ``magic numbers.'' This way, you can change the value of a constant once and not have to worry if you changed all occurrences. For example,

const int MAX_LENGTH = 30;

Although it is not preferred, you can also use the #define statement. For example,

#define MAX_LENGTH	30

(5) You should always put parenthesis around the replacement portion of a macro in a #define command to make certain things get interpreted the way you meant. Also, for macros with parameters, only pass values and not more complex expressions. For instance, if you have a macro

#define HALF(x)	((x) = (x) / 2)

you do not want to call this macro with this statement

result = HALF(number + 3);

as this will result in weird things which you probably do not want to happen!

Actually, for C++ (but not for C), there is a completely different way to implement macros without using a #define statement, which you should almost always prefer over a #define statement when it is practical. Its called an ``inline function'' and it has many advantages compared to a macro. We will probably cover these (briefly) in class at some point.

(6) All procedure declarations must have a return type specified. If a procedure does not have any return value, specify that procedure as void.

(7) Break long procedures down into sub-procedures. If your indenting runs you off the side of the page, you probably ought to break down the functionality into sub-procedures. Keep each procedure to performing one task (or several closely related tasks).

(8) Use a blank line whenever you feel you want to separate portions of code. Use blanks to make things ``look right'': if its easier to read, its better code.

(9) Try to abstract the functionality of the program away from the low-level data structures. ``Hide'' information which does not have to be seen. Make your support routines general enough so that they can be used in other programs, or so that they can handle multiple instances of a data type. For example, hash table routines should be able to handle more than one hash table, not just one global hash table. If you don't fully understand this hint, don't worry. It will become more apparent later on in the course as you start to do more advanced programming.