Chromium Java style guide

For other languages, please see the Chromium style guides.

Chromium follows the Android Open Source style guide unless an exception is listed below.

A checkout should give you clang-format to automatically format Java code. It is suggested that Clang's formatting of code should be accepted in code reviews.

You can propose changes to this style guide by sending an email to java@chromium.org. Ideally, the list will arrive at some consensus and you can request review for a change to this file. If there's no consensus, //styleguide/java/OWNERS get to decide.

Tools

Automatically formatting edited files

You can run git cl format to apply the automatic formatting.

IDE setup

For automatically using the correct style, follow the guide to set up your favorite IDE:

• Android Studio
• Eclipse

Checkstyle

Checkstyle is automatically run by the build bots, and to ensure you do not have any surprises, you can also set up checkstyle locally using this guide.

Lint

Lint is run as part of the build. For more information, see here.

File Headers

Use the same format as in the C++ style guide.

TODOs

TODO should follow chromium convention i.e. TODO(username).

Code formatting

• Fields should not be explicitly initialized to default values (see here).

Curly braces

Conditional braces should be used, but are optional if the conditional and the statement can be on a single line.

Do:

if (someConditional) return false;
for (int i = 0; i < 10; ++i) callThing(i);

or

if (someConditional) {
  return false;
}

Do NOT do:

if (someConditional)
  return false;

Exceptions

Similarly to the Android style guide, we discourage the use of catch Exception. It is also allowed to catch multiple exceptions in one line.

It is OK to do:

try {
  somethingThatThrowsIOException();
  somethingThatThrowsParseException();
} catch (IOException | ParseException e) {
  Log.e(TAG, "Failed to do something with exception: ", e);
}

Asserts

The Chromium build system strips asserts in release builds (via ProGuard) and enables them in debug builds (or when dcheck_always_on=true) (via a build step). You should use asserts in the same scenarios where C++ DCHECK()s make sense. For multi-statement asserts, use org.chromium.base.BuildConfig.DCHECK_IS_ON to guard your code.

Example assert:

assert someCallWithoutSideEffects() : "assert description";

Example use of DCHECK_IS_ON:

if (org.chromium.base.BuildConfig.DCHECK_IS_ON) {
  // Any code here will be stripped in Release by ProGuard.
  ...
}

Import Order

• Static imports go before other imports.
• Each import group must be separated by an empty line.

This is the order of the import groups:

1. android
2. com (except com.google.android.apps.chrome)
3. dalvik
4. junit
5. org
6. com.google.android.apps.chrome
7. org.chromium
8. java
9. javax

This is enforced by the Chromium Checkstyle configuration under the ImportOrder module.

Location

“Top level directories” are defined as directories with a GN file, such as //base and //content, Chromium Java should live in a directory named <top level directory>/android/java, with a package name org.chromium.<top level directory>. Each top level directory's Java should build into a distinct JAR that honors the abstraction specified in a native checkdeps (e.g. org.chromium.base does not import org.chromium.content). The full path of any java file should contain the complete package name.

For example, top level directory //base might contain a file named base/android/java/org/chromium/base/Class.java. This would get compiled into a chromium_base.jar (final JAR name TBD).

org.chromium.chrome.browser.foo.Class would live in chrome/android/java/org/chromium/chrome/browser/foo/Class.java.

New <top level directory>/android directories should have an OWNERS file much like //base/android/OWNERS.

Miscellany

• Use UTF-8 file encodings and LF line endings.