Java Style Guide

Inspiration

This style-guide is somewhat of a mash-up between the existing Java language style guides. The language guidance is drawn from the following:

• The Official raywenderlich.com Java Style Guide
• Google Java Style Guide

Table of Contents

• Naming
  • Packages
  • Classes & Interfaces
  • Methods
  • Fields
  • Variables & Parameters
  • Misc
• Declarations
  • Access Level Modifiers
  • Fields & Variables
  • Classes
  • Enum Classes
• Spacing
  • Indentation
  • Line Length
  • Vertical Spacing
• Getters & Setters
• Brace Style
• Switch Statements
• Annotations
• Testing
  • Test Classes
  • Test Methods
• Language

Naming

On the whole, naming should follow Java standards.

Packages

Package names are all lower-case, multiple words concatenated together, without hypens or underscores:

Preferred:

com.whitecloak.mypackage

Not Preferred:

com.whitecloak.my_package

Classes & Interfaces

Written in UpperCamelCase. For example MyClass.

Methods

Written in lowerCamelCase. For example myMethod.

Fields

Written in lowerCamelCase.

Static fields should be written in uppercase, with an underscore separating words:

public static final int MY_FIELD = 1;

Variables & Parameters

Written in lowerCamelCase.

Single character values to be avoided except for temporary looping variables.

Misc

In code, acronyms should be treated as words. For example:

Preferred:

XmlHttpRequest
String url
findPostById

Not Preferred:

XMLHTTPRequest
String URL
findPostByID

Declarations

Access Level Modifiers

Access level modifiers should be explicitly defined for classes, methods and member variables.

Fields & Variables

Prefer single declaration per line.

Preferred:

String username;
String twitterHandle;

Not Preferred:

String username, twitterHandle;

Classes

Exactly one class per source file, although inner classes are encouraged where scoping appropriate.

Enum Classes

Enum classes should be avoided where possible, due to a large memory overhead. Static constants are preferred. See http://developer.android.com/training/articles/memory.html#Overhead for further details.

Enum classes without methods may be formatted without line-breaks, as follows:

private enum CompassDirection { EAST, NORTH, WEST, SOUTH }

Spacing

Indentation

Indentation is using spaces - never tabs.

Blocks

Indentation for blocks uses 4 spaces

Preferred:

for (int i = 0; i < 10; i++) {
    Log.i(TAG, "index=" + i);
}

Not Preferred:

for (int i = 0; i < 10; i++) {
    Log.i(TAG, "index=" + i);
}

Line Wraps

Indentation for line wraps should use 8 spaces.

Preferred:

CoolUiWidget widget =
        someIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line);

Not Preferred:

CoolUiWidget widget =
     omeIncrediblyLongExpression(that, reallyWouldNotFit, on, aSingle, line);

Line Length

Lines should be no longer than 100 characters long.

Vertical Spacing

There should be exactly one blank line between methods to aid in visual clarity and organization. Whitespace within methods should separate functionality, but having too many sections in a method often means you should refactor into several methods.

Getters & Setters

For external access to fields in classes, getters and setters are preferred to direct access of the fields. Fields should rarely be public.

However, it is encouraged to use the field directly when accessing internally (i.e. from inside the class). This is a performance optimization recommended by Google: http://developer.android.com/training/articles/perf-tips.html#GettersSetters

Brace Style

Only trailing closing-braces are awarded their own line. All others appear the same line as preceding code:

Preferred:

class MyClass {
    void doSomething() {
        if (someTest) {
            // ...
        } else {
            // ...
        }
    }
}

Not Preferred:

class MyClass
{
    void doSomething()
    {
        if (someTest)
        {
        // ...
        }
        else
        {
        // ...
        }
  }
}

Conditional statements are always required to be enclosed with braces, irrespective of the number of lines required.

Preferred:

if (someTest) {
    doSomething();
}

if (someTest) { doSomethingElse(); }

Not Preferred:

if (someTest)
    doSomething();
    
if (someTest) doSomethingElse();

Switch Statements

Switch statements fall-through by default, but this can be unintuitive. If you require this behavior, comment it.

Alway include the default case.

Preferred:

switch (anInput) {
    case 1:
        doSomethingForCaseOne();
        // fall through
    case 2:
        doSomethingForCaseOneOrTwo();
        break;
    case 3:
        doSomethingForCaseOneOrThree();
        break;
    default:
        break;
}

Not Preferred:

switch (anInput) {
    case 1:
        doSomethingForCaseOne();
    case 2:
        doSomethingForCaseOneOrTwo();
        break;
    case 3:
        doSomethingForCaseOneOrThree();
        break;
}

Annotations

Standard annotations should be used - in particular @Override. This should appear the line before the function declaration.

Preferred:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
}

Not Preferred:

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
}

Testing

Test Classes

Test classes are named starting with the name of the class they are testing, and ending with Test. For example, MyClassTest or MyUtilTest.

Example:

class MyClassTest {

}

Test Methods

Underscores may appear in JUnit test method names to separate logical components of the name, with each component written in lowerCamelCase.

Test methods should follow the pattern methodUnderTest_shouldExpectedBehavior_whenStateUnderTest.

Example:

@Test
public void method_shouldThrowException_whenAgeLessThan18() { }

@Test
public void method_shouldFailToWithdrawMoney_forInvalidAccount() { }

@Test
public void method_shouldFailToAdmit_ifMandatoryFieldsAreMissing() { }

Language

Use US English spelling.

Preferred:

String color = "red";

Not Preferred:

String colour = "red";