Computer Science 202
Introduction to Programming
Fall 2013, The College of Saint Rose
Style Guide for CSC 202 Programs
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 significant component of your grade on programming assignments will be determined by your programming style.
This is a guide to help you better understand what we are looking for when we look at your programs. As the semester progresses there will be steeper penalties for styling mistakes. So get into the habit of writing good programs from the beginning. After writing your program, be sure to look over your code with the guidelines here in mind.
Commenting
Comments are extremely important. Take some care to write accurate yet concise comments.
You should write comments for:
private FramedRect playingArea;
might be:
// the main playing area in which the ball bounces
rather than, say,
// playing area
Frequently, several closely related 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 a blank line between methods. It is advisable to break up long method bodies and long declarations into logical pieces. Always start a new line after a semicolon.
Naming Literals
Do not use "magic numbers" in your method bodies. A magic number is a numeric constant embedded in code, without a constant definition. Any number except -1, 0, 1, and 2 should probably have a name that gives the number meaning. For example, rather than writing
ball.move(10, 20);
associate a static final variable with the numbers, defining a named constant:
private static final int BALL_MOVE_X = 10; private static final int BALL_MOVE_Y = 20;
and use the named constants in place of the numbers:
ball.move(BALL_MOVE_X, BALL_MOVE_Y);
Names
You should always choose names that suggest the meanings of the things being named. If the purpose of a method is to remove all the blanks from a string, then a good name for that method is removeBlanks. If there is a variable of type int that is used to refer to the total number of turns left in a game, then a good name might be turnsLeft or remainingTurns.
Names that have nothing to do with the program are very bad names! For example:
private FilledRect c3po;
would be a poor name unless the FilledRect happens to represent a shiny gold protocol droid with a British accent.
Names that are not specific or descriptive enough are generally bad names. For example:
FramedOval a;
would not be descriptive at all.
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,
Line line1; Line line2; Line line3;
are not as good as leftBlueLine, centerLine, and goalLine if they are being used to draw the lines for a hockey rink, for example.
Naming Conventions
The Java compiler is quite flexible about the names given to identifiers like class names, instance and local variables, and named constants. However, by convention, Java programmers (including us) will follow these rules:
Whenever possible, names should be declared as local variables rather than instance variables. Instance variables should only be used when a value must be saved for use after the execution of a method or constructor is completed.
Formatting
Your program should be formatted as neatly as possible. The statements and declarations placed in a method's body should be indented a few spaces more than the method's header. Similarly, the bodies of while loops and if statements should be indented slightly compared to the headers of these constructs. Sequences of statements that do not contain if statements, while loops or other control constructs should all be indented by the same amount.
BlueJ makes indentation easy to fix: select "Auto-Layout" from the "Edit" menu when you are editing a Java file and it will indent your code nicely.