CPSC 120 Java Style Guide

Spring 1998

Getting the computer to understand your program is no guarantee that people will be able to follow it. Just as you would edit an English composition, you should spend time revising a computer program to make it elegant and readable. The following guidelines will help you write programs that are easy to read and modify. The CPSC 120 graders will expect your Java assignments to conform to these style and documentation conventions.

1. Include a header comment at the top of each file.

The file header should include some standard information, followed by a brief description of the contents of the file and any special assumptions you have made.

• The first lines of the header should include the following standard information:
1. Your name (and the names of any people you work with--see the CPSC 120 collaboration policy)
2. Your section number (516, 517, or 518)
3. The name of the lab assignment (e.g., CPSC 120 Lab 1)
4. The date of last modification to the file.
• After the standard header information, describe the purpose of the class defined in that file. Be brief and informative. Communicate your approach to solving the problem.
• If you make any assumptions regarding the problem to be solved or about the kinds of inputs your program will accept, you must list these assumptions in a separate paragraph (labeled "ASSUMPTIONS:") at the end of the header comment. Deviations from the assignment should be listed as well. Keep in mind that any significant deviations should also be cleared with the instructor in advance. Specific assumptions regarding particular methods may be expressed as inline comments next to the relevant methods.

2. Include a header comment at the top of each class and method

• Identify each class with a block comment which stands out. The suggested format is

//*******************************************************************
//  The class name
//
// Description of the class
//*******************************************************************

Variations to this are acceptable, but more is not always better. The class name and a description of the purpose of the class is required.

• Identify each method with a block comment which is different from the class comment but still is noticable. The suggested format is

//-------------------------------------------------------------------
//  theMethodName
//
//Description of the method.
//-------------------------------------------------------------------

The method name must be included and the description. Describe the purpose of the method, details that are obvious to any programmer leave out. Items such as the type of the parameters do not need to be included, but the purpose of them should be.

3. Write self-documenting code.

• Choose meaningful names for all variables, parameters, classes, and methods. Use complete words instead of abbreviations where practical.
• Use named constants instead of sprinkling numbers throughout your code. This not only makes it easier to read the program, but also simplifies changing the values later because you only have to make the change in one place, where the constant is defined. (Test cases are an exception--use numbers there.) Rule of thumb: if a constant is used more than once, give it a name.
• The logic of your program should be clear from the text. Keep it simple. Avoid "clever" tricks that save a line of code at the expense of clarity.
• Avoid repetitious code by writing an appropriately named procedure and calling it multiple times.
• Be especially careful to keep boolean expressions simple. This will ensure readability and will help you avoid logic errors. Also, remember that there are simple ways to return the value of a boolean expression, other than testing it in a conditional statement that returns true or false:

BETTER STYLE:	GOOD STYLE:
return (height >= level);	if (height >= level) return true; else return false;

4. Follow standard formatting conventions.

• Capitalization:

variables and method names

the first letter is lower case, with the first letter of each subsequent word capitalized
for example, int caloriesFromFat = 18;

class names

the start of each word is capitalized
for example, public class VelocityVector {

constants

the entire name is capitalized
for example, public final double PI = 3.14159;

• Indentation:

braces

the open brace ({) goes at the end of the line before the start of the code block.
the close brace (}) goes on its own line, indented to match the beginning of the line containing the corresponding open brace, and include a descriptor on the closing brace line that indicates which opening brace it matches

code inside braces

indent one level for each level of curly braces ({})

code inside consequents

indent one level for consequents in conditional statements; omitting curly braces when the consequent is a single statement is possible but can be helpful in future coding

continued lines

when a statement continues across two or more lines, indent the second and remaining lines an equal amount past the start of the first line of the statement. See the example.

example:

public static boolean withdraw (int requestedAmount) {
   if (balance < requestedAmount)
      return false;
   else {
      balance = balance - requested amount;
      Terminal.println("Withdrawl of $" + requestedAmount +
                       " successful, leaving $" +
                        balance + ".");
      return true;
   }// end if
}// end method withdraw

• Order of variables and methods:

constants

if you define any constants, they should go first, with public constants before private ones

class variables (static variables)

if you define any static variables, put them immediately after the constants, listing the public variables first

instance variables

should follow the class variables, with the public ones first

constructors

should precede all other methods

public accessors

should immediately follow the constructors

other methods, public and private

can be listed in any logical order, with related methods near each other

the toString method

should be last so people can find it quickly

5. Use inline comments sparingly but whenever necessary.

• Use inline comments whenever the meaning of the code is not immediately obvious from the text. For example, inline comments can be useful to summarize cases in a conditional expression.

   if (xPosition < xLeft)               // left of box
      ...
   else if (xPosition > xLeft + width)  // right of box
      ...
   else if (yPosition < yBottom)        // below box
      ...
   else                                 // inside or above box
      ...

• Whenever possible, write self-documenting code to avoid the need for inline comments. The comment in the following example adds no information and should be omitted since it just wastes the reader's time.

   int RectangleWidth = 30;  // the width of the rectangle is 30

6. Present your test cases clearly and methodically.

Many of the CPSC 120 labs ask you to prepare a series of test cases to demonstrate that your program behaves in accordance with the specification in the assignment. The following guidelines should be followed in preparing test cases.

• Prepare a typed explanation of what test cases you chose and why you chose them. Summarize the results here.
• Test cases should be ordered logically, preferably in the same order as the code being tested.
• Whenever possible, choose test cases whose expected output can be quickly computed in your head (without the need for a calculator).
• When there are only a few possible inputs, test them all. Otherwise, choose test cases that exercise all branches of the code (for example, one test case that satisfies the condition in an if statement and a second test case that doesn't satisfy the condition).
• Be thorough. Pretend that you are an adversary trying to "trick" the program into giving the wrong answer. For example, test cases should include zero or negative values even if the "normal" case is a positive number. However, you are not obligated to test inputs that violate your stated assumptions.

7. Use common sense.

Remember that the CPSC 120 style guide is only a guide. Your primary concern should be making sure that others can read and understand the text of your program. If you think an additional comment or particular organization will get your ideas across more effectively, do it. However, if you are considering deviating significantly from the guidelines or if you are in doubt about something, please discuss it with us first.

This style guide was adapted from one prepared by Prof. Ken Goldman at Washington Univ. at St. Louis.