General Guidelines

next up previous
Next: About this document Up: No Title Previous: Indentation Style

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:

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

next up previous
Next: About this document Up: No Title Previous: Indentation Style

Kan Deng
Fri Jan 20 18:19:52 EST 1995