Commenting Instructions

As I mentioned on the first day of class, commenting is very important, particularly when we get to the harder problems. Every file, every class, every method, should have some description about its purpose. Within each of the methods, it is typically only necessary to explain "groups" of code. That is, you would describe what the main purpose of a particular loop is. It is not good practice to simply describe what the operation does. For example, the following would be bad: 
   // BAD Comment job...
   // Compute the value (a+b)/2 and store in c
   double c = (a + b)/2;
 
   // A better option...
   // Compute the midpoint of a and b 
   double c = (a + b)/2;

   // Still, you are stating the obvious!
   // Here is a better approach...
   double mid = (a + b)/2;

   // Yes, documentation can also be done by using good variable names!
The beginning of your program should ALWAYS contain the following information. 
// Your name
// Homework #X
// Class Name (e.g. Class HelloWorld)
// Due Date
// If given an extension: Extension Given Until (Date) - X% to be deducted.
//      That is, indicate extended due date and any points to be deducted for the extension.
// TA: Your TA's name (to make sure we have appropriate grader)
// Communicated with: List  (if you communicated in groups with others
//                           see Honor Code section in the Course Syllabus)
//
// Brief Description of assignment (e.g., Prints out Hello World)
Remember, it is a tricky issue. Too little commenting makes the code impossible to read. Too much commenting also makes the code impossible to read (information overload). Don't comment the obvious. Commenting is not a way to make code readable by a non-programmer. It is a way for a programmer to understand your specific code.

Pre and post conditions, etc.

When defining various methods in the class, if the information is not already supplied as it often will be, you should provide some documentation on every method you write. The main things to include are: This information can be found on page 8 of the course book.

For now, how it is presented inside your comment is not really important. I would try to mimic the way the book does it - as you can see by looking at the source code. It is fairly easy and geared towards javadoc. Later, we shall hopefully cover javadoc in a lab and then see how it produces nice HTML documentation automatically for you. At that point, you will have to write it using the javadoc format and it will be easier if you are already familiar with the notation... so practice it.

Your grader may have additional commenting requirements. In that case, they will contact you and explain their conditions. The first two programming assignments are grace periods to get the TA time to communicate their specific requirements to you. That is, they will mark your commenting but not deduct points for them.

Last modified: Mon Sep 15 12:56:26 EDT 2003