General

Every programming department has some set of standards or conventions that programmers are expected to follow. The purpose of these standards is make programs readable and maintainable. After all, you may be the programmer who maintains your own code more than six months after having written the original. While no two programming departments' standards/conventions may be the same, it is important that all members of the department follow the same standards. Neatness counts!!!

In general we will follow the Code Conventions for the Java Programming Language as developed Sun Microsystems. It is your responsibility to read, understand, and use these standards. In particular, graders will be looking for you to adhere to standards regarding:

1. File Names
2. Naming Conventions
3. Indentation and use of Whitespace
4. Comments

Comments are the programmer's main source of documentation.

From The Practice of Programming by Brian Kernighan and Rob Pike, page 23...

Comments are meant to help the reader of a program. They do not help by saying things that the code already plainly says, or by contradicting the code, or by distracting from the code with elaborate typographical displays. The best comments aid the understanding of a program by briefly pointing out salient details or by providing a larger-scale view of the proceedings.

Note that we will be discussing “documentation comments” in lab.

Naming

• All public Java classes are defined in a separate file. Name each file after the class it contains and give it a .java file extension. For example: if you have a class that represents a Car object, the class should be named Car and the file in which it is contained should be Car.java. When Car.java is compiled, the resulting Java byte code is found in Car.class.
• All class names use mixed case, with the first letter capitalized (e.g. RationalNumber). This is known as UpperCamelCase.
• Every data member of a class must be private.
• Variable and method names use mixed case with the first letter in lowercase (e.g. grandTotal). This is known as lowerCamelCase.
• Accessors/getters should typically be in the form of getSomething and mutators/setters should typically be in the form of setSomething. A notable exception are getters that return a boolean which are typically prefixed with “is” or “are” — e.g. isEmpty.
• The use of single letter variables is forbidden, except as simple for loop indices and in special cases such as x and y coordinates.
• The use of obvious, common, meaningful abbreviations is permitted. For example, “number” can be abbreviated as “num” as in numStudents or as “nr” in nrStudents.
• Use active function names, generally beginning with a verb and including a noun — e.g. getName( )
• Constants should appear in all capitals, word boundaries separated by underscores and should be used for magic numbers whenever possible — e.g. public static final int NUMBER_OF_LEGS = 4;

Class Comments

Every .java file should contain a “class header comment” describing the class within the file and containing other pertinent information. This comment must be a block comment that begins with /** and includes the following information. Some of this information will automatically be included when using Eclipse to create your .java files.

1. A description of the class including a statement of the class' invariant(s)
2. The date the file was created (shown below after the @version annotation)
3. Your name & UMBC email address (shown below after the @author annotation)
4. The project number
5. Your section number

For example:

/**
 * This class models a traditional table capable of containing 3 or 4 legs
 * with a ROUND, RECTANGLE or OVAL shape.
 *
 * @version 9/22/05
 * @author Bob Smith <bsmith22@gl.umbc.edu>
 * CMSC 202 - Spring 2011 - Project 1
 * Section 02
 */
public class Table {
    /* ...class definition... */
}

Method Comments

Method comments are the primary form of documentation for the user of our class methods. It is important that this documentation be both complete and accurate as it forms a “contract” between the class user and and the class implementer. These comments are sometimes referred to either as “documentation comments” or “interface comments.”

Each class method must have a comment that includes the following information. If you use Eclipse to write your code, it will add other important information for you (e.g. parameter names).

1. A description of the task that the method performs including any pre-condition(s) and post-condition(s).
2. Each parameter should be identified and be provided a brief description (shown below after the @param annotation). If there are any constraints on the parameters, say so.
3. If the method returns anything, it should be identified and possible values mentioned where applicable (shown below after the @return annotation).
4. If the method raises any exceptions, identify the exceptions raised and note the conditions that trigger that exception.

A pre-condition is a statement giving the condition(s) that is (are) required to be true when the method is called. The method is not guaranteed to perform correctly unless the pre-condition is (are) true. It is NOT just a restatement of the parameter names and types. All methods must test for pre-conditions to the extent possible. Until we learn about exceptions, if a false pre-condition can be handled in code, do so (see the calculateCircleArea method below).

A post-condition is a statement describing what will be true when the method call is completed (assuming the pre-condition is met and the method completes).

For example, a method that calculates the area of a circle might have a header like this.

/**
 * Calculates the area of a circle given its radius.
 * The radius provided should be greater than zero.
 *
 * @param radius the radius of the circle (must be greater than zero)
 * @return the calculated area of the circle, or zero if an invalid
 *         radius was supplied
 */
double circleCircleArea(double radius) {
   // handle unmet precondition
   if (radius < 0.0) {
      return 0.0;
   } else {
      return Math.PI * radius * radius;
   }
}

Inline Comments

Unlike class and method level comments, inline comments are intended for individuals that need to update, modify and maintain your code. As such, they should aid in the understanding of the code and clarify what non-straightforward or complex code is doing.

For example, the following code contains enough higher-level inline documentation to help the reader understand what's going on. However, simple or self-explanatory statements (e.g. the 3 assignments that make up the swap on lines 8–10) are not (and should not) be documented.

public static void bubbleSort(int[] numbers) {
  // start at back, reducing length each iteration
  for(int i = numbers.length - 1; i > 0; i--) {
    // sweep though from 0 to current length
    for (int j = 0; j < i; j++) {
      // if these 2 adjacent numbers are out of order, swap
      if (numbers[j] > numbers[j+1]) {
        int temp = numbers[j];
        numbers[j] = numbers[j+1];
        numbers[j+1] = temp;
      }
    }
  }
}

A Larger Example

The following illustrates what a file that adheres to these standards might look like.

package proj1;

/**
 * Represents a modern motor vehicle consisting of a make (e.g. Audi),
 * model (e.g. A8), year of manufacture (e.g. 2011) and a paint color
 * (e.g. PaintColor.BLACK). The make, model and paint color may not be
 * null, and the year of the vehicle must be greater than 1900.
 *
 * @version 01/27/2011
 * @author Dwight Schrute <dwightschrute@umbc.edu>
 * @project CMSC 202 - Spring '11 - Project 3
 * @section 02
 */
public class Vehicle {

    /**
     * The make of the vehicle (e.g. Audi)
     */
    private String make;

    /**
     * The model of the vehicle (e.g. A8)
     */
    private String model;

    /**
     * The 4-digit year the vehicle was produced (e.g. 2011)
     */
    private int year;

    /**
     * The paint color of the vehicle (e.g. PaintColor.BLACK)
     */
    private PaintColor color;

    /**
     * Sole constructor - creates a new Vehicle instance.
     *
     * @param make the make of the vehicle (must not be null)
     * @param model the model of the vehicle (must not be null)
     * @param year the 4-digit year the vehicle was produced
     *             (must be greater than 1900)
     * @param color the paint color of the vehicle (must not be null)
     */
    public Vehicle(String make, String model, int year, PaintColor color) {

        // ...code to perform error checking here...

        this.make = make;
        this.model = model;
        this.year = year;
        this.color = color;
    }

    /**
     * Checks to see if the vehicle qualifies as historic under
     * MD state law.
     *
     * @return true if the vehicle is considered historic, false
     *         otherwise
     */
    public boolean isHistoric() {

        boolean historic = false;

        // ...code to check to see if vehicle is historic here...

        return historic;
    }

    /**
     * Gets the color of the vehicle
     *
     * @return the current vehicle color
     */
    public PaintColor getColor() {
        return color;
    }

    /**
     * Updates the vehicle as having the new paint color
     * (i.e. the vehicle has been repainted)
     *
     * @param color the new paint color
     */
    public void setColor(PaintColor color) {
        this.color = color;
    }

    /**
     * Gets the make of the vehicle
     *
     * @return the make of the vehicle
     */
    public String getMake() {
        return make;
    }

    /**
     * Gets the model of the vehicle
     *
     * @return the model of the vehicle
     */
    public String getModel() {
        return model;
    }

    /**
     * Gets the year the vehicle was manufactured
     *
     * @return the year the vehicle was manufactured
     */
    public int getYear() {
        return year;
    }

    /*
     * (non-Javadoc)
     * @see java.lang.Object#toString()
     */
    public String toString() {
        return color + " " + make + " " + model + " (" + year + ")";
    }

}