Code Documentation Plan (Page 3)

<<Back 1 2 3 Next>>

General Coding Standards

Variables

All variables (except of type bool) will be nouns named with capital letters. Boolean variables will be adjectives or verbs named the suffix “ed” except where they make incorrect grammatical sense. Underscores will be used only to separate text portions of the variable name from numerical portions of the variable name.

Allowed:
bool Named_123
bool Placed_999

Not-Allowed:
bool Founded123
bool isItName123

Declarations

One declaration per line is to be used and followed by a short inline comment to document its significance and use. This convention is to be followed even if variables are of the same type.

Allowed:
int Sum; //Sum of all the incoming data.
int Input; //The current input from the loop.
char FirstName[80]; //Buffer for user’s first name.
char LastName[80]; //Buffer for user’s last name.

Not-Allowed:
int Mikes_Sum; //Sum for incoming data
char Array_1[80], Array_1[80];
float Mikes_floater_variable; //float variable for stuff

Functions & Function Prototypes

Functions and Prototypes will limit arguments to one argument per line followed with a short inline documentation. This convention makes code more readable and easier to follow. Functions will be named with a lowercase verb followed by nouns named with capital letters. Passing by value is encouraged, but the writers of this document understand that sometimes passing by reference is necessary. Try to limit these occasions.

Allowed:
float returnAverage(float Table[ ], //Data to find the
//average
int NumberOfItems //The number of items in
//the table
bool RoundOff); //decides if returned
//value will be rounded
//to the nearest int.

Not-Allowed:
float AverageData(float mytable[],
int number, //number of items in
//table
bool Round_Yes_Or_no); //round off

Documentation and in-line comments

Any significant operation or declaration will require a brief inline comment. Insignificant operations not necessary of documentation are those such as updating a pointer to the next character in a string or documentation of the pre-increment or post-increment operators. When in doubt if an operation is significant, ask yourself a simple question. “Would a first year Computer Science Undergraduate understand this?” If the answer is yes, then nothing more is necessary. Otherwise, more documentation is needed.

Necessary: int Total; //Sum total of all values in the set

Not-Necessary: p++ //increment p for the next iteration
//of the loop

The following function documentation shall be used as templates for all functions in this project.

C++ Function Documentation

// function name: <name goes here>
// parameters-in: <list them one per line with a short description>
// parameters-out: <list them one per line with a short description>
// parameters-in/out: <list them one per line with a short description>
// returns: <what value does the function return or void>
// description of function: <A full and complete description of what the
// function does and how it does it will go in this field>
// notes: <any other information a developer finds helpful should go in
// here (e.g., “use this function only for floating point data”)>

Note that this is the standard for documenting functions and is different from how documentation for functions that access classes will be handled. An example of documentation on how functions that access classes are handled is shown in the class documentation section above.

<<Back 1 2 3 Next>>