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...)

• 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 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,

#define MAX_LENGTH	30

Some people may tell you that in C++ you shouldn't use a #define statement at all for constants. In this class, the use of the #define statement is perfectly acceptable. However, the same effect can be had without this statement, but by using the type-specifier const. For technical reasons, the latter approach is considered better form: if you're curious as to how this works, ask one of the TA's or professors.

(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, only pass values to macros with parameters, do not pass expressions or statements. 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.