Commenting Your Code: The Course Standard

Commenting Your Code: The Course Standard

--------------------------------------------------------------------------------

Contents
Introduction
File Headers
Class Headers
Function Headers
In-line Comments
Revising Given Code
Grading

--------------------------------------------------------------------------------

Introduction
Part of learning to write program code involves learning how to comment the code effectively and meaningfully. This document is our attempt to provide you with guidelines not only for this class, but also for future projects.

The first question we must address when discussing code commenting is, why comment? Mainly, comments are added to increase human understanding of the program code. First and foremost, comments help you, the programmer, remember what you've done. This is especially important when debugging your code. Well-placed comments can be very helpful in determining whether the code actually does what you think it does. Comments that provide an ``outline'' of the algorithm can remind you what is happening at each stage of the program and also show us, the instructors, that you do know what's going on, even if it doesn't work correctly.

Comments will also be useful when others are trying to determine what your code does. Specifically, if you come to office hours with a question, comments can help us help you better. Also, if anyone (including you) sees your code at a much later date, the comments will provide insight into design decisions that you may not remember or that you may not be available to explain.

Okay, so we agree that commenting code is a Good and Useful Practice. Now, why must we have a standard? In terms of this course, a standard gives us a way to evaluate your comments as part of the grading for each MP. Also, we know that standards are used extensively in industry, and we want you to gain experience working within prescribed parameters. However, because of the scope of this course, we will only be applying a standard to comments, rather than to your entire program.

The remaining sections of this handout will detail where comments should be found and what they should look like. In the final section you will find a few words about how this standard will be used to determine your MP grades. If you have any questions about the standard, check with one of the TAs, either via the newsgroup or in office hours.



--------------------------------------------------------------------------------

File Headers
The top of each file will contain a short header comment. This comment will give the following information:
the name of the file
a brief statement of the contents of the file
the author's name
the date the file was created
the machine problem to which it belongs
For example:


/**********************************************************
* Interface.C -- part of MP3
*
* These functions provide the user interface for acctmgr.
*
* Author: Wendy Barth
* Date: 10 May 1993
*/


As long as the prescribed information is present, you may choose the specific format for comment symbols, spacing, etc. For example, the following format of the Interface.C header is also acceptable:


//============================================================
// Interface.C -- MP3
// These functions provide the user interface for acctmgr.
//
// Author: Wendy Barth
// Date: May 10, 1993
//============================================================



--------------------------------------------------------------------------------

Class Headers
If more than one class is contained within a file, each class will have a short header stating the following:

the class name
what, if any, classes it is derived from
a brief description of the class
For example:


/**********************************************
* Class: Two_D_Object
* Derived from: Geometric_Object
*
* Objects of this class are two-dimensional
* entities. All the member functions of
* of the Geometric_Object class are inherited,
* and a definition of fillPattern() is added.
*/



--------------------------------------------------------------------------------

Function Headers
Each function declaration and definition will be preceded by a short comment stating the following:

what the function does (not how it does it)
the role of each input value
any assumptions the function makes about the input values
any guarantees the function makes about its output value
For example:

A function with no parameters:

// yesOrNo returns 1 if the answer given is yes,
// 0 if the answer given is no,
// and -1 if the answer is neither.
//
int yesOrNo();


A function with parameters:

// processAcct reads the command contained in cmdfile
// and makes appropriate changes to the account database.
// It returns 0 if no errors are encountered. Otherwise,
// 1 is returned with an appropriate error message in err.
int processAcct(char *cmdfile, char *err);



--------------------------------------------------------------------------------

In-line Comments
Comments that appear interleaved with the code should adhere to the following guidelines:

They should provide an outline of the function.
They should explain what the code is doing without restating the code itself.
They are necessary only when it is not obvious what the code is doing. To determine ``obviousness'', ask yourself the question ``If I had never seen this code before, or even hadn't seen it for a week, how long would it take me to determine what this section does?'' If the answer is anything longer than 1 minute, include a comment.
They should appear at the closing brace of long blocks to help the reader determine which opening brace it is paired up with.


--------------------------------------------------------------------------------

Revising Given Code
If we provide you with code that must be modified, comments relating to the modified code should be updated to reflect the changes. The updates will involve adding the following information to the appropriate headers:

the date of modification
the name of the person who performed the modifications
a brief statement of the revisions
For example, given the original user interface of acctmgr, Steve Student made some modifications. The new file header is:


/**********************************************************
* Interface.C -- part of MP3
*
* These functions provide the user interface for acctmgr.
*
* Author: Wendy Barth
* Date: 10 May 1993
* Update: 11 May 1993 by Steve Student
* - modified for error-checking and
* prettiness
* 13 May 1993 by Steve Student
* - added yesOrNo function
* 17 May 1993 by Steve Student
* - made isWheel return correct value
*/

Similar update statements should also appear in class headers, function headers, and in-line comments, as appropriate.



--------------------------------------------------------------------------------

Grading
The comment portion of each MP grade will be determined by the presence of your comments and your adherence to the standard. Although the number of points ascribed to ``comments'' may not seem that large, your ability to comment effectively and consistently is a skill you will need for future projects. This is especially true if you will be involved with any large software development projects. Comments will not only allow you to understand your own code better, they will allow those who follow you to understand it as well. Thus, it is in your best interest to include comments according to the standard.