Use the following template prior to each function definition

// Function: FUNCTION_NAME

//

// Purpose: EXPLAIN WHAT THIS FUNCTION DOES TO SUPPORT THE

     //        CORRECT OPERATION OF THE PROGRAM, AND HOW IT DOES

     //        IT.

//

// Parameters:

     // parameter_name (IN, OUT, or IN/OUT) -- EXPLANATION OF

     //    THE PURPOSE OF THIS PARAMETER TO THE FUNCTION.

//    (REPEAT THIS FOR ALL FORMAL PARAMETERS OF THIS FUNCTION.

//

// Returns: IF THIS FUNCTION SENDS BACK A VALUE VIA THE

     //        RETURN MECHANISM, DESCRIBE THE PURPOSE OF THAT

     //        VALUE HERE.

 

IN = USED TO PASS DATA INTO THIS FUNCTION,

OUT = USED TO PASS DATA OUT OF THIS FUNCTION

IN/OUT = USED FOR BOTH PURPOSES.

 

Example of a Good Functional Comment Block

 

// Function: FIND_BIGGEST_QUAKE

//

// Purpose: Identify the earthquake from the list of earthquake

//    intensities (quake_list) that has the largest magnitude.

//    It is assumed that the given list of quake intensities is

//    an array-based list of unordered Richter Scale

//    magnitudes; this function performs a simple sequential

//    search through the array to locate the position of the

//    largest magnitude (the largest value) in the list.

//

// Parameters:

//    quake_list (IN) -- the array of earthquake magnitudes. This

//        is just an array of real numbers; the first magnitude

//        is assumed to be at index 0.

//    num_entries (IN) -- the quantity of magnitudes in quake_list.

//

// Returns: The index (position) of the largest earthquake

//    magnitude in the quake_list array.

 

 

A programmer reading this comment will have a good understanding of the

operation of the function and this knowledge will make reading the code

easier, should the programmer find that to be necessary. (It's possible

that all they needed to know about this function was found in the comment.)

 

Note that the description of the subprogram includes the algorithm(s)

used to carry out the work of the routine, but includes no details about

the implementation of the algorithm(s). Readers who want that level of

detail will need to read the code.

 

Also note that this comment could have been written before the subprogram

was written! This is not unusual at all; when you write your code,

you should be following a detailed outline that you developed first.

Your block comments can be written based on your outline of the operation

of the routine. In other words, there is no excuse for you to wait until

the last minute to do your commenting!