CS61B Style Guide
Author: Alan Yao

Note: It is probably easier to get to know these rules by running the automated style checker, since most of them won't make sense until you are a Java expert. You can do this by submitting to the autograder or by running the style61b.py script on your Java files.

To run the style61b.py script, first make sure you have the latest skeleton by running git pull skeleton master in your repository. Ensure that the course libraries are on your classpath as set up. If you don't know how to do so, take a look at (this guide from the spring offering of CS61B)[http://cs61b.ug/sp16/materials/lab/lab3b/lab3b.html#a-windows-setup]. Note that a few things will differ: your login is two letters, and our folder is called lib, not javalib, and of course as always, your directory structure will vary. For example on Mac or Linux, if your repo name is ab, then you want /PATH/TO/YOUR/REPOSITORY/REPLACE/ab/lib to be on the class path and do so by adding export CLASSPATH='/PATH/TO/YOUR/REPOSITORY/REPLACE/ab/lib:.' to the end of your ~/.bashrc.

You will also need to download the checkstyle jar:

https://github.com/Berkeley-CS61B/skeleton-sp16/raw/master/javalib/checkstyle-6.15-all.jar

Place the checkstyle jar in your lib folder. DO NOT add this to your repository (it is ignored by default).

Then navigate to your lib folder (or javalib if that's what it's named), and find the style61b.py script. You can move this script around or leave it here; either way, you run it by doing the following command:

python style61b.py [list of paths to files to style check]

For example, if you wanted to style check all the java files in the current directory, you would do:

python style61b.py *.java

The below is a set of rules that our style checker attempts to check for, and that you should follow. These are adapted from the Google and Sun style guides (which are industry standards) and made more lenient for your programming ease. Credit to Paul Hilfinger, for writing the original guide.

Whitespace

  1. Each file must end with a newline sequence.
  2. Files may not contain horizontal tab characters. Use blanks only for indentation.
  3. No line may contain trailing blanks.

  4. Do NOT put whitespace:

    1. Around the < and > within a generic type designation (List<Integer>, not List <Integer>, or List< Integer >).
    2. After the prefix operators !, --, ++, unary -, or unary +.
    3. Before the tokens ; or the suffix operators -- and ++.
    4. After ( or before ).
    5. After .

  5. DO put whitespace:

    1. After ;, ,, or type casts (e.g., (String) x, not (String)x).
    2. Around binary operators (e.g., *, +) and comparison operators.
    3. Around assignment operators (e.g., =, +=).
    4. Around ? and : in the ternary conditional operator (x>0 ? x : -x).
    5. Around the keywords assert, catch, do, else, finally, for, if, return, synchronized, try, and while.

  6. In general, break (insert newlines in) lines before an operator, as in

    ... + 20 * X
    + Y;
  7. Do not separate a method name from the ( in a method call with blanks. However, you may separate them with a newline followed by blanks (for indentation) on long lines.

Indentation

  1. The basic indentation step is 4 spaces.

  2. Indent code by the basic indentation step for each block level (blocks are generally enclosed in { and }), as in

    if (x > 0) {
    r = -x;
} else {
    r = x;
}

  3. Indent case labels an indent past their enclosing switch, as in

    switch (op) {
    case '+':
        addOpnds(x, y);
        break;
    default:
        ERROR();
}
  4. Indent continued lines by the basic indentation step.

Braces

  1. Use { } braces around the statements of all if, while, do, and for statements.

  2. Place a } brace on the same line as a following else, finally, or catch, as in

    if (x > 0) {
    y = -x;
} else {
    y = x;
}
  3. Put the { that opens a block at the end of a line. Generally, it goes at the end of the if, for, while, switch, do, method header, or class header that contains it. If line length forces it to the next line, do not indent it, and put it alone on the line.

Comments

  1. Methods should have javadoc comments explaining the behavior, parameters (using @param tags or otherwise), and return type.
  2. Methods that return non-void values must describe them in their Javadoc comment either with a @return tag or in a phrase in running text that contains the word "return", "returning", or "returns".
  3. Each Javadoc comment must start with a properly formed sentence, starting with a capital letter and ending with a period.

Names

  1. Names of static final constants must be in all capitals (e.g. RED, DEFAULT_NAME).
  2. Names of parameters, local variables, and methods must start with a lower-case letter, or consist of a single, upper-case letter.
  3. Names of types (classes), including type parameters, must start with a capital letter.
  4. Names of packages must start with a lower-case letter.
  5. Names of instance variables and non-final class (static) variables must start with either a lower-case letter or _.

Imports

  1. Do not import the same class or static member twice.
  2. Do not import classes or members that you do not use.

Assorted Java Style Conventions

  1. Write array types with the [] after the element-type name, not after the declarator. Write String[] names, not String names[].
  2. Write any modifiers for methods, classes, or fields in the following order:
  3. public, protected, or private.
  4. abstract or static.
  5. final, transient, or volatile.
  6. synchronized.
  7. native.
  8. strictfp.
  9. Do not explicitly modify methods, fields, or classes where the modification is redundant:
  10. Do not label methods in interfaces or annotations as public or abstract.
  11. Do not label fields in interfaces or annotations as static, public, or final.
  12. Do not label methods in final classes as final.
  13. Do not label nested interfaces static.

  14. Do not use empty blocks ('{ }' with only whitespace or comments inside) for control statements. There is one exception: a catch block may consist solely of comments having the form

     /* Ignore EXCEPTIONNAME. */
  15. Do not try to catch the exceptions Exception, RuntimeError, or Error.
  16. Write b rather than b == true and !b rather than b == false.

  17. Replace

    if (condition) {
    return true;
} else {
    return false;
}

    with just

    return condition;
  18. Only static final fields of classes may be public. Other fields must be private, protected, or package protected.
  19. Classes that have only static methods and fields must not have a public (or defaulted) constructor.
  20. Classes that have only private constructors must be declared final.

Avoiding Error-Prone Constructs

  1. If a class overrides equals, it must also override hashCode.
  2. Local variables and parameters must not shadow field names, unless it is for a setter or a constructor.
  3. Do not use nested assignments, such as if ((x = next()) != null) .... Although this can be useful in C, it is almost never necessary in Java.
  4. Include a default case in every switch statement.

  5. End every arm of a switch statement either with a break statement or a comment of the form

    /* fall through */

  6. Do not compare String literals with ==. Write

    if (x.equals("something"))

    and not

    if (x == "something")

    There are cases where you really want to use ==, but you are unlikely to encounter them in this class.

Limits

  1. No file may be longer than 2000 lines.
  2. No line may be longer than 100 characters.
  3. No method may be longer than 100 lines.
  4. No method may have more than 8 parameters.
  5. Every file must contain exactly one outer class (nested classes are OK).