C++ Programming

Source Code Documentation Requirements

1. comment following each brace } indication which block is closed. Examples :

} //end while
} // end for i
} // end main
} // end calcAvg

2. commenting header file or include compiler directives.

All include statements must have a comment indicating why the file is included.

For example nearly every program will include iostream.h. and use cout and cin. The include statement should look like this:

#include<iostream.h> // cout, cin

If the power function in math.h is used then the include statement would look like this:

#include<math.h> // pow

if setw(), setprecison(), and setiosflags() are used, the include statement should look like this:

#include<iomanip.h> // setw, setprecision, setiosflags

3. Magic Numbers

Magic number is any number appearing in an expression.
Magic numbers must have a descriptive comment clearly explaining WHAT the number represents and HOW it is being used.
Magic numbers can be avoided by declaring a constant with an appropriate descriptive identifier.

General rule to follow using comments or constants when using a number in an expression.

If a number is used multiple places in the program then it should probably be declared as a constant. If not you will be writing a comment every time the number is used.
If a number is used one time in the program then the programmer has the choice of using a comment or declaring a constant.

Example: Suppose a program is written to determine the number of busses needed for a field trip. Let's say each bus can hold 32 students. The following expression which calculates the number of full busses required is

fullBusses = students / 32 ;
//32 is how many students can occupy a bus. Calculate the number of full busses need.

NOTE the WHAT and HOW! This is required in every magic number comment.

If the programmer does not what to write a comment each time 32 would be used then a constant should be used such as

const int BUS_CAPACITY = 32 ;

Remember the constant identifier should be descriptive of what it represents! This would declaration would lose some credit :

const int BUS = 32 ;

However if the programmer combines a constant declaration with a comment then this would not lose any credit:

const int BUS = 32 ; // How many students can occupy one bus.