Reference: Kim B. Bruce, Andrea Pohoreckyj Danyluk, and Thomas P. Murtagh, Java: An Eventful Approach.

The presentation of your program is just as important as its correctness. While good comments or good variable names will not affect the correctness of your program, they will make it easier to read your program.

Readability of code is important for several reasons. First, it is an important way for you to keep track of your thoughts as you design and write your program. The more careful you are about organizing your thoughts, the less likely it is for your code to be error-prone. In the event that there are problems with your code, you will be able to debug it more easily if you can read and follow the work you have done. Second, it will allow others to better understand what you have written. This is particularly important if you are working on a team project or if you are writing code that will be modified over time.

This appendix outlines general rules of good programming style. There are many other sources of style guidelines that you might consult as well, including those at http://java.sun.com/docs/codeconv. While most style guides provide roughly the same advice, there are some places where they might dier. When in doubt, consult with your instructor to learn his/her style preferences.

A.1 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 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. In particular, if you have written and then commented out code, remove it.

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.
   
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 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!
   
3. Variables and constants: In general, variables and constants should all have comments as to what the variable is used for. Occasionally several closely related variables or constants can be grouped together under the same comment.

A.2 Blank Lines

Blank lines are used to delineate dierent areas of the code. The instance variable declarations at the top of your program should be separated from the header of the class and the header of the first method. There should always be space between methods. It is advisable to break up long method bodies and long declarations into logical pieces. Always start a new line after the semicolon. Always leave a blank line before a comment line.

A.3 Names

You should always choose names that suggest the meanings of the things being named. If the purpose of a method is to draw a rectangle, then a good name for that method is drawRect. If there is a variable of type FilledRect that is used as the stem of a flower, then a good name would be stem or stemRect.

• Names that have nothing to do with the program are very bad names! Ex. FramedRect frodo .
• Names that are not specific or descriptive enough are generally bad names. Ex. Line line or Line l are not as good as Line foulLine if the line represents a foul line.
• Try not to name objects sequentially. You should only do this when the objects are related in some way that is not otherwise expressible. For example, FramedRect box1, FramedRect box2, FramedRect box3 are not as good as darksBasket, whitesBasket, and colorsBasket if the rectangles represent laundry baskets for clothes of specific colors.

By convention, constants (indicated by “static final” in Java) are all capital letters, classes begin with uppercase, variable and method names begin with lowercase, while uppercase is used to start new words in multi-word names. Instance variables should never be declared to be public.

Instance variables should only be used when a value must be saved for use after a constructor or method has been completed. Otherwise local variables should be used.

A.4 Format

Your program should be organized as neatly as possible. The structure of the text in the program should give the reader an overall sense of the program’s logical organization. Indent the bodies of methods. Also indent the bodies of loops, as well as the then and else parts of if statements.