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. Any line of comment or
code that is over 80 characters will not print. If it does not
print, the TA will not be able to read it. Consider revising or writing 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. Remove all code
that you comment out.
You should write comments for:
- 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.
- Methods: Above each method heading there
should be a brief description of what the method does. You should
also describe what each parameter means and what the return result
means. 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 areas that you deem to be
complicated. Be careful not to overcomment!
- 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.
