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 over-comment! Over-commenting 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 each:

1. Class or Object (Program): At the top of each file you should write your name, date of creation, and a brief description of what is contained in the file. (E.g., a list of objects and classes contained in it.) 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.

   For each class or object expression, please include a brief paragraph explaining what it does (what is more important than how here). This comment should also explain any parameters used in the class definition.

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 over-comment!

   For method headers the style is:

   	// Tell what the method should do (but not how!)
   	// explain what each parameter represents
   	// explain what is returned if the return type is different from Done
       

3. Variables and defs: In general, variables and defs should all have comments as to what the identifier is used for. For example a good comment for your def diagonal: Line 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