CS 341 Style Guide

The way you present your program is just as important as having a correct program. While having good comments or good variable names will not affect the correctness of your program, it will make it easier to read your program. It is important that others be able to understand your code so that they can modify your code if they have to. A significatn portion of your grade on programming assignments will be determined by your programming style.

This is a guide to help you better understand what I am looking for when I look at your labs. After writing your programs be sure to look over your code and your style.

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 comment lines too long. Any line of comment or code that is over 80 characters will not print. 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 program with commented out code. Remove all code that you comment out. The one exception is that you can include commented out code if you feel you made significant progress on a piece of functionality but couldn't quite get it working. In that case, also describe what you did and what you think is wrong with it.

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. Occasionally several closely related private variables or constants can be grouped together under the same comment.

Blank Lines

Blank lines are used to delineate different 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.

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 stop sign, 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, particularly for instance variables. Ex. Line line or Line l are not as good as Line foulLine if the line represents a foul line. For parameters and local variables, simple names are often sufficient.
Try not to name objects sequentially. You should only do this when the objects are related in some way that is not otherwise expressible. Ex., 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.

Format

Your program should be organized as neatly as possible. Always select Eclipse's format command from the Source menu frequently to keep your program readable. Be sure to select format to reformat your program before turning it in.

Import Statements

Each import statement should import a single, specific class, like:

import javax.swing.JComponent;

Eclipse makes this easy using the Source menu, Organize Imports command. The reason to do this is so that somebody who reads your code will be able to tell where each class comes from.

Constants

Your program should generally not contain literals, like the number 37. Instead you should define a constant, like:

private static final int RECT_WIDTH = 37;

This serves two purposes. First, it makes it clear what a value means and whether two occurrences of 37 are coincidental or are intentionally the same. It also makes it much easier to change your program when you want to change it.

Eclipse makes it easy to change an embedded literal into a constant. Use the Refactor menu and select Extract Constant. It will create the constant definition for you and, if you select "Replace all occurrences..." it will replace all occurences of the literal with that constant.

As a corollary to this, you should define constants in terms of each other when possible, like this:

private static final int RECT_WIDTH = 37; private static final int RECT_LEFT = 20; private static final int RECT_RIGHT = RECT_LEFT + RECT_WIDTH;

Now if you change either the width or left, the value for the right will be automatically updated. Make the computer do the work!