Java Style

2019 status: Current

To help you with these style conventions, we strongly suggest that you import the settings file for your project. The buendia repo contains intellij-idea-settings.jar and the client repo contains android-studio-settings.jar. You can import them with the File > Import Settings... command, available in both IntelliJ IDEA and in Android Studio. Once you have imported these settings, the Reformat Code command (Command-Option-L on a Mac) will automatically reformat and rearrange code as described here.

Fight verbosity

• Lines and characters are valuable and take up space both on the screen and in the mind; spend them wisely and eliminate or minimize redundant information.

• Never write JavaDoc or comments that duplicate the name of a class or method or duplicate the semantics of the code. It is okay to write a comment as a section heading that summarizes the purpose of a group of statements, to help others navigate through the code. But never write a comment like this:

      i += 1;  // Increment i
  

  And do not document methods like this:

      /** Returns the colour. */
      Colour getColour() {
          ...
      }
  

  For a method with an obvious name like getColour, it is better to not write any JavaDoc at all than to waste space on a useless comment like /** Returns the colour. */

• Keep names short when context is obvious. For example, if you are naming a local instance of ConcertGrandPiano and there are no other pianos in scope, don't automatically name the variable concertGrandPiano; just call it piano. If you must use more characters, spend those characters to convey useful additional meaning.

• Avoid using highly repetitive names, as they are harder to tell apart. For a method to compute a GCD, int gcd(int a, int b) is better than int gcd(int number1, int number2).

• If a variable is defined and then used only once in an expression, eliminate the variable and substitute it at the place where it is used (unless the expression is too complex). For example, do not write:

  String message = "The time is " + new SimpleDateFormat("HH:mm").format(new Date()) + ".";
  return message;
  

Instead, simply write: return "The time is " + new SimpleDateFormat("HH:mm").format(new Date()) + ".";

Naming

• Form camel-case names by capitalizing based on where there would be spaces between words in normal writing, treating initialisms and acronyms as regular words. For example, there are three words in the phrase "XML HTTP request", so XmlHttpRequest is correct and XMLHTTPRequest is not.

• Classes:

  • Class names should be nouns.
  • Static classes should generally have plural names (e.g. Lists, FooUtils).
  • All other classes should never have plural names.

• Methods:

  • Method names should be verbs or verb phrases.
  • For JavaDoc, use a third-person declarative phrase, not a second-person imperative phrase (e.g. write "Changes the background colour" instead of "Change the background colour").

• Packages:

  • If a package name describes what most of the classes in it are examples of, the package name should be plural (e.g. widgets for a package of widget classes).
  • Otherwise use an appropriate singular theme or topic (e.g. for a package containing various classes related to colour, the name colour is better than colours because the classes themselves are not colours).

• Variables:

  • Instances of Collections (arrays, lists, sets, maps) should have plural names, e.g. a List of Concepts should be named concepts unless there is a specific reason otherwise. Prefer concepts to conceptList.
  • Variables that are not collections and not iterable should never have plural names.
  • Maps can be named with a plural noun that describes the values (not the keys), or a name of the form "valuesByKey". For example, a Map of Concepts keyed by their UUIDs could be named concepts or conceptsByUuid.
  • Use the "m" prefix for names of non-public instance members and "s" for names of non-public static members. Do not use these prefixes on public members.

Arranging code

• Arrange the contents of classes in the following order:

  • public fields (static first)
  • non-public fields (static first)
  • public enums and interfaces
  • public methods (static first, then constructors, then others)
  • public inner classes
  • non-public enums and interfaces
  • non-public methods (static first, then constructors, then others)
  • non-public inner classes

• In general, put higher-level code before lower-level code; try to make calls point downward in the file rather than upward. For example, if method x() calls y(), put x() before y().

• Within methods, define variables as close as possible to the scope in which they are used.

• Use javax.annotation.Nullable and javax.annotation.Nonnull to help IntelliJ flag potential NPEs. Place the @Nullable or @Nonnull annotation immediately before the type of the variable or method, e.g. public @Nullable String foo(@Nonnull String bar).

Line breaks

• Use single-line if or else without braces when the entire body is just break, continue, or return with a simple expression.

• Otherwise, always indent and use braces around if, else, for, and while blocks.

• /** When JavaDoc fits on one line, write it in single-line style. */

• Avoid a line break after @Override.

• When line-breaking a long expression, put the operator (e.g. +, &&, .) at the beginning of the next line.

• Keep lines less than 100 characters long.

Indentation

• Indent with spaces only, never tab characters.

• Indent blocks by 4 spaces; also indent continuation lines by 4 spaces.

• When there are many indented lines enclosed in parentheses, arrange the parentheses as you would do with braces (line break immediately after the open paren, indented contents, line break immediately before the unindented closing paren).

Whitespace

• Never use spaces between a method name and an immediately following open-parenthesis.

• Always use one space between a keyword and an immediately following open-parenthesis.

• Use spaces inside braces that surround code, e.g. void doNothing() { }.

• Do not use spaces immediately inside all other braces, square brackets, angle brackets, or parentheses, e.g. new String[] {"foo", "bar"}.

• Use no spaces before and one space after each comma.

• Use spaces around binary operators in general, e.g. a + b. You may omit spaces to convey precedence, e.g. 2*a + 3*c. Do not put a space after unary operators such as !, -, +.

• In code, never use multiple consecutive spaces; use just one.

• In comments, use two spaces between sentences.