Block Comment Templates with Examples

Block Comment Templates with Examples
C and Pascal versions, September 2000
(McCann)

Here are the block commenting templates to use for internal and external block comments in your programs. If you do not yet understand where these templates are to be used, take a look at the programming style example for your language (C or Pascal) on my Programming Style Documents page. Toward the bottom of this document are examples of internal block comments, along with some commentary about their quality. Hopefully they will help you understand what makes an internal block comment a good one. (See the Programming Style Documents page for an example of an external block comment.)

Using the Templates

The idea behind have these templates is that you can use your text editor to add a template to your code and then just type in the appropriate information for each section in the template. This will help you because it saves you some typing and makes sure you don't leave out an entire section of information.

To include these in your source code file on a lab machine, edit your source code file, position your cursor on a blank line at the point in your code where you wish to place a template, and then use your editor's file-reading command to read in the template you want. For example, in vi the command to include a file is :r filename. So, to read in the internal.c template, you'd give the vi command of:

:r /home/student/Classes/mccann/general/templates/internal.c

Then all you need to do is fill in the template with the details of the function you are trying to document.

Another option is to copy the templates to your directory, delete the explanation text from your copies, and add common information to them that you'd always enter (such as your name in the external block comment template). Then you can add these "pre-editted" blocks to your program and speed up the commenting process even further.

Templates for C:

internal.c:


        /*------------------------------------------------- FUNCTION_NAME -----
         |  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.
         |                       IN = USED TO PASS DATA INTO THIS FUNCTION,
         |                       OUT = USED TO PASS DATA OUT OF THIS FUNCTION
         |                       IN/OUT = USED FOR BOTH PURPOSES.)
         |
         |  Returns:  IF THIS FUNCTION SENDS BACK A VALUE VIA THE RETURN
         |      MECHANISM, DESCRIBE THE PURPOSE OF THAT VALUE HERE.
         *-------------------------------------------------------------------*/

external.c:


/*=============================================================================
 |   Assignment:  ASSIGNMENT NUMBER AND TITLE
 |
 |       Author:  STUDENT'S NAME HERE
 |     Language:  NAME OF LANGUAGE IN WHICH THE PROGRAM IS WRITTEN AND THE
 |                      NAME OF THE COMPILER USED TO COMPILE IT WHEN IT
 |                      WAS TESTED
 |   To Compile:  EXPLAIN HOW TO COMPILE THIS PROGRAM
 |
 |        Class:  NAME AND TITLE OF THE CLASS FOR WHICH THIS PROGRAM WAS
 |                      WRITTEN
 |   Instructor:  NAME OF YOUR COURSE'S INSTRUCTOR
 |     Due Date:  DATE AND TIME THAT THIS PROGRAM IS/WAS DUE TO BE SUBMITTED
 |
 +-----------------------------------------------------------------------------
 |
 |  Description:  DESCRIBE THE PROBLEM THAT THIS PROGRAM WAS WRITTEN TO
 |      SOLVE.
 |
 |        Input:  DESCRIBE THE INPUT THAT THE PROGRAM REQUIRES.
 |
 |       Output:  DESCRIBE THE OUTPUT THAT THE PROGRAM PRODUCES.
 |
 |    Algorithm:  OUTLINE THE APPROACH USED BY THE PROGRAM TO SOLVE THE
 |      PROBLEM.
 |
 |   Required Features Not Included:  DESCRIBE HERE ANY REQUIREMENTS OF
 |      THE ASSIGNMENT THAT THE PROGRAM DOES NOT ATTEMPT TO SOLVE.
 |
 |   Known Bugs:  IF THE PROGRAM DOES NOT FUNCTION CORRECTLY IN SOME
 |      SITUATIONS, DESCRIBE THE SITUATIONS AND PROBLEMS HERE.
 |
 *===========================================================================*/

Templates for Pascal:

internal.pas:


        {*----------------------------------------------- SUBPROGRAM_NAME -----
         |  (Procedure OR Function) SUBPROGRAM_NAME
         |
         |  Purpose:  EXPLAIN WHAT THIS SUBPROGRAM 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 SUBPROGRAM.
         |                      (REPEAT THIS FOR ALL FORMAL PARAMETERS OF
         |                       THIS SUBPROGRAM.
         |                       IN = USED TO PASS DATA INTO THIS SUBPROGRAM
         |                       OUT = USED TO PASS DATA OUT OF THIS SUBPROGRAM
         |                       IN/OUT = USED FOR BOTH PURPOSES.)
         |
         |  Returns:  IF THIS IS A FUNCTION, DESCRIBE THE PURPOSE OF ITS
         |      RETURN VALUE HERE.
         *--------------------------------------------------------------------}

external.pas:


{*=============================================================================
 |   Assignment:  ASSIGNMENT NUMBER AND TITLE
 |
 |       Author:  STUDENT'S NAME HERE
 |     Language:  NAME OF LANGUAGE IN WHICH THE PROGRAM IS WRITTEN AND THE
 |                      NAME OF THE COMPILER USED TO COMPILE IT WHEN IT
 |                      WAS TESTED
 |   To Compile:  EXPLAIN HOW TO COMPILE THIS PROGRAM
 |
 |        Class:  NAME AND TITLE OF THE CLASS FOR WHICH THIS PROGRAM WAS
 |                      WRITTEN
 |   Instructor:  NAME OF YOUR COURSE'S INSTRUCTOR
 |     Due Date:  DATE AND TIME THAT THIS PROGRAM IS/WAS DUE TO BE SUBMITTED
 |
 +-----------------------------------------------------------------------------
 |
 |  Description:  DESCRIBE THE PROBLEM THAT THIS PROGRAM WAS WRITTEN TO
 |      SOLVE.
 |
 |        Input:  DESCRIBE THE INPUT THAT THE PROGRAM REQUIRES.
 |
 |       Output:  DESCRIBE THE OUTPUT THAT THE PROGRAM PRODUCES.
 |
 |    Algorithm:  OUTLINE THE APPROACH USED BY THE PROGRAM TO SOLVE THE
 |      PROBLEM.
 |
 |   Required Features Not Included:  DESCRIBE HERE ANY REQUIREMENTS OF
 |      THE ASSIGNMENT THAT THE PROGRAM DOES NOT ATTEMPT TO SOLVE.
 |
 |   Known Bugs:  IF THE PROGRAM DOES NOT FUNCTION CORRECTLY IN SOME
 |      SITUATIONS, DESCRIBE THE SITUATIONS AND PROBLEMS HERE.
 |
 *============================================================================}

Examples of Good and Bad Block Comments

Contrary to popular student opinion, I don't require all of the commenting as an annoyance to you. It has been estimated that about 70% of programming effort is put into the maintenance of old code, and the rest into the development of new code. It is safe to assume that, should you do some programming in your career, that you will be needing to modify someone else's code to fix an old bug or to extend the code's functionality. Commenting exists to help those unfortunate programmers who have to look at the code months or years after it was written. When you write comments for your code, keep that in mind and include useful information rather than details that are plainly obvious. The future programmers will know the language; you don't need to explain what "i < j" means! Instead, explain why it's important that this condition be checked at this point in the code. Do you understand the difference?

As an example, let's imagine that you're going to write a subprogram that searches a list of earthquake intensities to find the most powerful quake. (I'm using this simple example to make my points; you upper-level students might find this excessively trivial, but students in lower-level courses read this page, too, and I don't want to lose them.)

I am not going to show any code for this routine; this is intentional! The internal block comment is meant to give an overview of the construction and operation of the routine. If the reader wants more detail, he or she can move on to read the code, which will have its own comments about the code itself.

A Bad Internal Block Comment

Here's our first example of a block comment for our earthquake intensity search routine. This is not an actual example from a student program, but it does (I hope!) capture most of the mistakes students make when they wait until the last minute to write a comment:

        /*-------------------------------------------- FIND_BIGGEST_QUAKE -----
         |  Function FIND_BIGGEST_QUAKE
         |
         |  Purpose:  Find the biggest earthquake.
         |
         |  Parameters:
	 |	quake_list (IN) -- the quakes
	 |	size (IN) -- size of the list
         |
         |  Returns:  The biggest quake
         *-------------------------------------------------------------------*/

What's wrong with this comment?

The description of the purpose of the function is useless; we could have figured as much from the name of the function alone!
The structure of the quake_list parameter is not even mentioned.
How is the list size measured? By number of items or by index position of the last item?
Exactly what about the biggest earthquake is being returned? Its position in the list? Its measured size? The entire entry from the list?

Again, the point is that anyone reading this comment will have learned almost nothing about this function. You are forcing the reader to wade through the code to learn anything of substance.

A Good Internal Block Comment

Compare the first attempt to this one:

        /*-------------------------------------------- FIND_BIGGEST_QUAKE -----
         |  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.
         *-------------------------------------------------------------------*/

Obviously, this comment includes many more details. 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!