Java Programming Style Guide

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 grader may expect your assignments to conform to these style and documentation conventions.

• Include a header comment at the top of the class containing the "main" method (if application) or at the top of the class that contains the "extends Applet" method (if applet). This header should contain:
  1. Your name (and the names of any people you work with)

  2. The course number (e.g., CPSC 211) and your section number (e.g., 201-203)

  3. The name of the programming assignment (e.g., Program 1)

  4. The date of last modification to the file.

  5. Under the heading "PURPOSE", describe the purpose of the code in that file. Be brief and informative. Communicate your approach to solving the problem.

  6. Under the heading "ASSUMPTIONS", state assumptions you make regarding the problem to be solved, the kinds of inputs your program will accept, and deviations from the assignment requirements (note that any significant deviations should be cleared with the instructor in advance.) This header must include:
     • any assumptions made about the input
     • limitations of the program with regard to the requirements
     • known bugs
     Specific assumptions regarding particular methods may be expressed in block comments above the relevant methods.

• Include a brief header block comment at the top of each class that is not the "main" or "extends Applet" class AND at the top of each method within each class. The format is shown below:

  //*******************************************************************
  //  The class or method name
  //
  // Description of the class or method purpose
  //*******************************************************************
  

• 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 as follows:

     
     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
        ...
  

• Write self-documenting code.
  1. Choose meaningful names for all variables, parameters, classes, and methods. Use complete words instead of abbreviations where practical.

  2. Use named constants instead of sprinkling numbers throughout your code. Rule of thumb: if a constant is used more than once, give it a name.

  3. Avoid repetitious code by writing an appropriately named procedure and calling it multiple times.

• 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 word 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 (about 3 spaces) for each level of curly braces ({})

    code inside conditional statements and loops

    indent one level for lines of code in conditional statements and loops; omitting curly braces when the conditional or loop contains a single statement is possible, but curly braces can be helpful in future coding and can aid in debugging

    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.

    Example of proper indentation technique:
    

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

  • 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

    local variables

    should be declared as close as possible to their point of use.

    for example, a variable used as a counter in a for loop can be declared as follows:
    for (int i = 0; i < 10; i++)

• Use common sense. Remember that this 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 by Jenny Walter and Jennifer Welch from one prepared by Prof. Ken Goldman at Washington University at St. Louis.