Commenting

Commenting

Comments are extremely important. Take some care to write accurate yet concise comments.

• Be specific with your comments. What happens when the mouse is pressed? What is the FilledRect used for? Your comments should describe the intent of the code. What are you trying to accomplish with this piece of code?
• Do not make your comments too long. Depending on the program used for printing, a line of comment or code that is over 80 characters either will not print or will wrap around to a new line in a fairly unreadable fashion. If it does not print, the TA or instructor will not be able to read it. Either revise it or write it on multiple lines.
• Do not overcomment! Overcommenting can make the program hard to read just as much as under-commenting. Do not comment every line. If they are simple instructions, most people will understand them without your comments. If you think you need commenting, try commenting chunks of code under the same comment.
• Delete any extraneous code that is not used. You would not hand in an English paper with crossed out lines. Similarly, you should not hand in a lab with commented out code unless there is a good reason you want the instructor to look at it, e.g., you tried something that didn't work and you want help in understanding why. Aside from that, remove all code that you comment out and any comments that are no longer relevant.

You should write comments for:

1. Class (Program): At the top of each class, you should write your name, date of creation, and a brief description of what the class is for. If you decide to do more than the assignment requested, you should describe these "extra" features in the program under the class description. Sometimes it's hard to tell a bug from a feature.

   Comments for classes headers should use the Javadoc block comment style. For classes these should use the following style:

   	/**
   	 * Tell what the class does here as well as why and when you wrote it.  
   	 * Let us know if there is something different than was specified in the 
   	 * assignment (i.e., extra credit).
   	 * @author <your name here>
   	 */
       

2. Methods: Above each method heading there should be a brief description of what the method does. You should also describe what each parameter means, how each parameter contributes to the final result, and what the return result means. The details of "how" are much less important than an accurate description of "what".

   If the method code is simple you do not need to comment in the method body. If the method body is complicated, you might want to add some comments to certain blocks of code that you deem to be complicated, e.g., the different branches of an if-else statement, or what a loop is accomplishing. Be careful not to overcomment!

   For method headers the style is:

   	/**
   	 * Tell what the method should do (but not how!)
   	 * @param paramName -- what the parameter represents
   	 *  Include an @param line for each parameter
   	 * @return what is returned
   	 *  An @return line is needed if the method returns anything but void
   	 */
       

3. Variables and constants: In general, variables and constants should all have comments as to what the variable is used for. For example a good comment for your variable Line diagonal in NoClicking would be: // the slash in the prohibit sign. Occasionally several closely related variables or constants can be grouped together under the same comment. These comments are usually placed on the line above the declarations.

Commenting