Coding Practices

Naming
Programming practices

Naming

GJSG 5 Naming is normative, with the amendments below.

Method names are written in lowerCamelCase.

Method names are typically verbs or verb phrases. For example, sendMessage or stop.

Underscores may appear in JUnit test method names to separate logical components of the name, with each component written in lowerCamelCase. One typical pattern is <methodUnderTest>_<state>, for example pop_emptyStack. There is no One Correct Way to name test methods.

Indeed, there is no One Correct Way to name test methods—or any method, for that matter. However, in this bootcamp, we add the following requirements on method (and test method) names:

Methods must be named using verbs or verb phrases, except for methods without parameters that return simple properties of an object that are not directly settable (e.g., size(), length()), and conversion or static factory methods whose names start with from, to, or of.
Accessor and mutator pairs must follow the JavaBeans naming conventions—that is, using get and set prefixes for non-boolean-valued properties, and is and set prefixes for boolean-valued properties.

If a given accessor has no corresponding mutator, then either the JavaBeans convention or the simple accessor naming pattern (described in the point above) may be used for the accessor.
Test method names must begin with the name of the method under test. (Test methods for constructors are addressed in the following point.) Any additional name components must be separated from the name of the method under test, and from each other, by underscores; each name component must be written in lowerCamelCase.
Names of test methods intended to test behavior of constructors must begin with constructor, initialize, or init; addtional components must be separated and cased as described above.

GJSC 5.2.5 Non-constant field names:

Non-constant field names (static or otherwise) are written in lowerCamelCase.

These names are typically nouns or noun phrases. For example, computedValues or index.

GJSC 5.2.6 Parameter names:

Parameter names are written in lowerCamelCase.

One-character parameter names in public methods should be avoided.

GJSC 5.2.7 Local variable names:

Local variable names are written in lowerCamelCase.

Even when final and immutable, local variables are not considered to be constants, and should not be styled as constants.

For this bootcamp, names are further constrained:

Parameter names must consist of 2 or more characters each, except for catch parameters and lambda parameters, which may have single-character names. The following rules in this list do not apply to single-character names for catch or lambda parameter names.
When constructing a lowerCamelCase name, avoid names beginning with a single lowercase character, followed immediately by an uppercase character. Such names are easily mistyped, and can cause problems in automatic generation of setters and getters. For example, while the name of the OAuth authentication standard might intuitively lead to a field name such as oAuthKey, oauthKey is preferred.
Field, parameter, and local variable names of all scalar types (primitives, wrappers, String) except boolean and Boolean, must be singular nouns or noun phrases.
boolean or Boolean fields, parameters, and local variables must be named using adjectives or adjective phrases.
Fields, parameters, and local variables that are references to arrays and collections must be named with plural or collective nouns or noun phrases. For example, in a card game application, we may have a field (or several) of type List<Card>. Both cards and deck would be acceptable names for such a field: the former is a plural noun, and the latter is a collective noun.
Do not name boolean or Boolean fields with prefixes such as is, are, or has. (The is prefix is part of the JavaBeans specification for accessor methods, not fields. Also, all of these prefixes make the field name a verb phrase, rather than an adjectival phrase.)
Do not use Hungarian notation for field, parameter, or local variable names. That is, do not prefix the name with type or role identifiers.
Avoid unnecessary suffixes on field, parameter, and local variable names. For example, prefer
```
private List<String> words;
```
to
```
private List<String> wordList;
```
Similarly, while the m and s prefixes on non-public, non-static and static fields (respectively) are often seen in Java source code (including the Android library source code), these are also unnecessary, and should be avoided.
If a non-static field is intended to act as a primary key value of a persistent instance (e.g., a field annotated with @PrimaryKey in an entity class), prefer the simpler id to {entity name}Id.

Note that there are a few long-standing exceptions to the naming & casing rules listed in GJSG and above. For example, UUID is a class in the Java standard ibrary, written as indicated in UPPERCASE; however, uuid (rather than uUID) is the correct way to use that initialism as a field or variable name.

Programming practices

GJSG 6 Programming Practices is normative, with the amendments and additions below.

GJSG 6.2 Caught exceptions: not ignored:

Except as noted below, it is very rarely correct to do nothing in response to a caught exception. (Typical responses are to log it, or if it is considered “impossible”, rethrow it as an AssertionError.)

When it truly is appropriate to take no action whatsoever in a catch block, the reason this is justified is explained in a comment.

…

Exception: In tests, a caught exception may be ignored without comment if its name is or begins with expected. The following is a very common idiom for ensuring that the code under test does throw an exception of the expected type, so a comment is unnecessary here.
try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

While expected (or ignored) should be used for exceptions that are expected and will not require any special handling, the justification must be explained in a comment within the catch block. For example, the code immediately above is not acceptable, but the following is:

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
  // Exception is expected if code functions as intended.
}

Types

If a non-static field is intended to act as a non-compound primary key value of a persistent instance (e.g., a field annotated with @PrimaryKey in an entity class), the type of the field must be one of:
- long or Long (preferred)
- UUID
- int or Integer
Though the type selected should be independent of the RDBMS being used, it’s often the case that the latter influences the former. For example, when using SQLite, the most performant—and appropriate—choice for the type of a field intended for use as a non-compound primary key value is long or Long.

Access level modifiers

Class members are declared at the lowest practical access level.
The only fields allowed to have the public access level are those marked final. (Note that interface fields are implicitly public static final, as are the enumerated values of an enum class.)
Non-static fields, even if final, must not be public, except in inner/nested private classes, anonymous classes, or local classes.
Prefer protected accessors and mutators over protected fields.

`if`-`else if` ladders

An if-else if statement ladder should include a final else, especially when one or more of the following holds:
- else if occurs multiple times in the ladder.
- The purpose of the ladder is to assign one of a number of alternative values to a field.
- The purpose of the ladder is to assign one of a number of alternative values to a local variable, and that variable is not declared immediately before the ladder.

Naming

Programming practices

Types

Access level modifiers

if-else if ladders

`if`-`else if` ladders