CSE132 Style Guide

NOTE: Here is an example of code that conforms to this 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. Beginning with Lab 2, the CSE 132 TAs will expect your assignments to conform to these style and documentation conventions. A large portion of your lab grade is based on style, so don't assume that it's good enough to just get your program running. Read this Style Guide carefully, and let us know if you have any questions.

  1. Before each class definition, provide a Javadoc header comment with the following information: If you have more than one class in a file, headers for subsequent classes in a file need only the brief description of the purpose of the class.

  2. Before each method, provide a Javadoc comment that describes what the method does, and the meaning of each parameter, and its return value (if any). Eclipse will help you set this up. After typing the method header, go to the line immediately above the method header and type the characters /** and then hit the enter key. Eclipse will set up a method comment with the parameter names. Complete the header as in the following example:
    	 * Deposits the given amount into the account.
             * REQUIRES: The given amount is positive.
    	 * @param amount the dollar amount to deposit
    	 * @return the new balance
    	 public int deposit(int amount) {
                if (amount < 0)
                   throw new IllegalArgumentException("positive amount required");
                balance += amount;
                return balance;
    In all comments, be brief and informative. Since the CSE 132 TAs are already familiar with the assignment, please don't repeat the details of the assignment. Instead, communicate your approach to solving the problem.

    Note: You do not need to write Javadoc comments for your JUnit test methods, but some inline comments may be necessary to explain what case the particular test is checking, if it's not immediately obvious from the test code itself.

  3. Choose meaningful names for all variables, parameters, classes, and methods. Use complete words instead of abbreviations. For example, use width instead of w. (However, if an assignment specifies a particular name, please don't choose a different one.)

  4. Use named constants instead of sprinkling numbers throughout your code. For example, if a paint program has a standard brush size of 5 pixels, don't just put the number 5 all over the code. Instead, define and use a constant at the top of the class, like this:
             static final int BRUSH_SIZE = 5;
    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.

  5. The logic of your program should be clear. Keep it simple. Avoid "clever" tricks that save a line of code at the expense of clarity.

  6. Avoid duplicating code by writing an appropriately named procedure and calling it where neeeded.

  7. Be especially careful to keep boolean expressions simple. This will ensure readability and will help you avoid logic errors. Also, remember to simply return the value of a boolean expression, rather than testing it in a conditional statement that returns true or false:
    return (height >= level);
    if (height >= level)
       return true;
       return false;

  8. Follow standard formatting conventions.
  9. 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 DirectionVector {
    the entire name is capitalized
    for example, public static final double PUPIL_FRACTION = 4;

    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 (an exception is "else" which goes on the same line as the closing brace for the corresponding "if", so the closing brace for the "if" doesn't appear on its own line)
    code inside braces
    indent one level for each level of curly braces ({})
    code inside consequents
    use curly braces and indent one level for consequents in conditional statements (braces may be omitted if there is only one statement in a consequent, but some editors expect the braces in order to do automatic indentation properly)
    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.
    public static boolean withdraw (int requestedAmount) {
       if (balance < requestedAmount) {
          return false;
       } else {
          balance = balance - requested amount;
          System.out.println("Withdrawl of $" + requestedAmount +
                           " successful, leaving $" +
                            balance + ".");
          return true;

    TIP: Eclipse will help correct your indentation. Select the section of the file you want to correct, and then choose "correct indentation" from the "source" menu.

    Order of variables and methods within a class definition:
    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
    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

  10. Use brief inline comments whenever the meaning of the code is not immediately obvious. 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

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

  12. When a CSE 132 assignment asks for test cases, present your test cases clearly and methodically.

  13. Be professional. Use the same care in preparing your code as you would for any writing assignment. Avoid jokes in your code, slang terms, crude comments, etc.
  14. Use common sense. Remember that the CSE 132 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, discuss it with us first.