Java Style

Fight verbosity

• Lines and characters are valuable; eliminate or minimize redundant information.
• Never write JavaDoc or comments that duplicate the name of a class or method (e.g. /** Gets the thing */ for getThing()) or the semantics of the code (e.g. /** Increment i. */ for i += 1).
• Keep names short when context is obvious. For example, if you have one instance of AppPatientDelta in scope, name it delta rather than appPatientDelta (unless necessary to distinguish it from something else named "delta" in scope).
• 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, consider eliminating the variable and substituting it into the place where it is used.

Naming

• Class names should be nouns and method names should be verbs or verb phrases.
• For normal classes, never use plural names. For static classes, generally use plural names (e.g. Lists, FooUtils).
• If a package name describes what the classes in it are examples of, the package name should be plural (e.g. widgets for a package containing widget classes).
• Collections (arrays, lists, sets, maps) should always have plural names, e.g. a List of Concepts should be named concepts unless there is a compelling reason otherwise. Prefer concepts to conceptList.
• Avoid plural names for variables that are not collections and not iterable.
• Maps often have names in the form "valuesByKey", e.g. a Map of Concepts keyed by their UUIDs should be named conceptsByUuid or simply concepts if there are no other collections of Concepts in scope.
• Use the "m" prefix for names of instance members and "s" for names of static members.
• Form camel-case names by capitalizing based on where spaces would go between words in normal writing, treating initialisms and acronyms as regular words, e.g. XmlHttpRequest is correct, XMLHTTPRequest is not.

Arranging code

• Arrange class members in the following order at the top of the class:
  • public static
  • public
  • non-public static
  • non-public
• Arrange methods in the following order:
  • constructor
  • public static methods
  • public methods
  • non-public static methods
  • non-public methods
• In general, put higher-level code before lower-level code; make calls point downward in the file rather than upward. For example, if a method x() calls methods y() and z(), put x() first.
• Within methods, define variables as close as possible to the scope in which they are used.
• 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 when the entire body is just break, continue, or return.
• Otherwise, always 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.

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 multiple spaces within code; use just one.
• 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.
• In general, use spaces around operators in general, e.g. a + b. You may omit spaces to convey precedence, e.g. 2*a + 3*c.