Block Comment Templates with Examples

Block Comment Templates with Examples
(McCann)
Last Updated: August 2015

Here are the block commenting templates to use for internal and external block comments in your programs.

Toward the bottom of this document are two 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. If you're taking a lower-level programming class, see the example code for that class for additional documentation examples.

Why Block Comments?

Consider the Java API documentation. Each class starts with a (usually lengthy) description of the purpose of the class and how it fits into the Java class hierarchy. That's a block comment. Each method has a similar block of documentation associated with it. Without these comments, the programmer would have a hard time using the class or its method effectively. You should do the same for your code. Java's API is documented using a commenting style that is compatible with a tool called Javadoc. That's great for documentation that lots of people will be referencing, but not so good for commenting one-off student programs. So, we don't use Javadoc, but we do require that you write complete, well-structured block comments for your classes and methods.

In addition, you need to place a block comment ahead of the class containing your main() method. We call this an `external' block comment because it replaces the external documentation that would normally accompany a complete program.

Using the Templates

To make entering block comments as painless as possible, we supply outlines of each type of block comment. The idea behind having these templates is that you can use your 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 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.txt template, you'd give the vi command of:

:r /cs/www/people/mccann/templates/internal.txt

Then all you need to do is fill in the template with the details of the method 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.

Java Templates:

internal.txt and int.txt:

An internal block comment belongs immediately ahead of each method of your program, with two exceptions. First, main() is assumed to be covered by the external block comment. Second, if your class has a group of getters and setters, you may cover the entire group with one block comment. The file internal.txt has exactly what you see below. int.txt is just the box and section names; it's easier to import into your code, because you don't have to delete the explanations before entering your own text.

       /*---------------------------------------------------------------------
        |  Method [Method Name]
        |
        |  Purpose:  [Explain what this method does to support the correct
        |      operation of its class, and how it does it.]
        |
        |  Pre-condition:  [Any non-obvious conditions that must exist
        |      or be true before we can expect this method to function
        |      correctly.]
        |
        |  Post-condition: [What we can expect to exist or be true after
        |      this method has executed under the pre-condition(s).]
        |
        |  Parameters:
        |      parameter_name -- [Explanation of the purpose of this
        |          parameter to the method.  Write one explanation for each
        |          formal parameter of this method.]
        |
        |  Returns:  [If this method sends back a value via the return
        |      mechanism, describe the purpose of that value here, otherwise
        |      state 'None.']
        *-------------------------------------------------------------------*/

class.txt and cl.txt:

Each class you write, except the class containing main(), must have a block comment of this form ahead of it.

/*+----------------------------------------------------------------------
 ||
 ||  Class [Class Name] 
 ||
 ||         Author:  [Your Name]
 ||
 ||        Purpose:  [A description of why this class exists.  For what
 ||                   reason was it written?  Which jobs does it perform?]
 ||
 ||  Inherits From:  [If this class is a subclass of another, name it.
 ||                   If not, just say "None."]
 ||
 ||     Interfaces:  [If any predefined interfaces are implemented by
 ||                   this class, name them.  If not, ... well, you know.]
 ||
 |+-----------------------------------------------------------------------
 ||
 ||      Constants:  [Name all public class constants, and provide a very
 ||                   brief (but useful!) description of each.]
 ||
 |+-----------------------------------------------------------------------
 ||
 ||   Constructors:  [List the names and arguments of all defined
 ||                   constructors.]
 ||
 ||  Class Methods:  [List the names, arguments, and return types of all
 ||                   public class methods.]
 ||
 ||  Inst. Methods:  [List the names, arguments, and return types of all
 ||                   public instance methods.]
 ||
 ++-----------------------------------------------------------------------*/

external.txt or ext.txt:

At the top of the file containing your program's main() method, place an `external' block comment containing the following content.

/*=============================================================================
 |   Assignment:  Program #[n]:  [Assignment Title]
 |       Author:  [Your Name (Your E-mail Address)]
 |       Grader:  [Your TA or Section Leader's name]
 |
 |       Course:  [Course Number]
 |   Instructor:  L. McCann
 |     Due Date:  [Due Date and Time]
 |
 |  Description:  [Describe the program's goal, IN DETAIL.]
 |
 |     Language:  [Programming language and version used.]
 | Ex. Packages:  [List names and sources of all external packages
 |                required by this program.]
 |                
 | Deficiencies:  [If you know of any problems with the code, provide
 |                details here, otherwise clearly state that you know
 |                of no unsatisfied requirements and no logic errors.]
 *===========================================================================*/

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, 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 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:

        /*---------------------------------------------------------------------
         |  Method FIND_BIGGEST_QUAKE
         |
         |  Purpose:  Find the biggest earthquake.
         |
         |  Pre-condition: Earthquakes are available.
         |
         |  Post-condition: We found the biggest one.
         |
         |  Parameters:
	 |	quakeList -- the quakes
	 |	size      -- size of the list
         |
         |  Returns:  The biggest quake
         *-------------------------------------------------------------------*/

What's wrong with this comment? Most everything! Where to start?

The description of the purpose of the function is useless; we could have figured as much from the name of the method alone! What we really need to know is exactly what job this method performs. For instance, it would be really nice to know what "biggest" means in this context. Largest measure on the Richter Scale? Most damage caused?
Pre- and Post-conditions are supposed to tell us what needs to be true before (Pre-) and after (Post-) this method executes. They need to be clear and unambiguous, not wishy-washy. These are wishy-washy.
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 method. 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:

        /*---------------------------------------------------------------------
         |  Method FIND_BIGGEST_QUAKE
         |
         |  Purpose:  Identify the earthquake from the list of earthquake
	 |	intensities (quakeList) 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.
         |
         |  Pre-condition: quakeList holds 1 or more intensities; the
         |      intensities are in no particular order; numEntries holds
         |      the exact number of entries currently in the list.
         |
         |  Post-condition: quakeList and numEntries are unchanged; the 
         |      list position of the entry with the largest magnitude has 
         |      been identified; the position is within the boundaries
         |      of the array.
         |
         |  Parameters:
	 |	quakeList -- the array of earthquake magnitudes.  This
	 |		is an array of real numbers; the first magnitude
	 |		is assumed to be at index 0.
	 |	numEntries -- the quantity of magnitudes in quakeList.
         |
         |  Returns:  The index (position) of the largest earthquake
	 |	magnitude in the quakeList array.
         *-------------------------------------------------------------------*/

Obviously, this comment includes many more details. A programmer reading this comment will have a good understanding of the operation of the method and this knowledge will make reading the code easier, should the programmer find that to be necessary. (It's very possible that all they needed to know about this method 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 (nay, should 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!