Master Google’s Java Style Guide: Essential Formatting Rules for Clean Code

Overview

Defines the Google Java Style Guide rules that a Java source file must satisfy to be considered compliant.

Terminology

In this guide class includes ordinary classes, enums, interfaces, and annotation types; comment refers to implementation comments (Javadoc).

Source File Basics

File name

The file must be named after its top‑level class, case‑sensitive, with the .java extension.

Encoding

All source files use UTF‑8 encoding.

Whitespace and characters

Only the ASCII space character (0x20) may appear as whitespace; tabs are forbidden.

Special characters such as \, ", ' must be escaped with standard escape sequences, not octal or Unicode escapes.

Non‑ASCII characters may be used directly when they improve readability; otherwise use Unicode escapes and comment their meaning.

Source File Structure

The ordered sections are: optional license/header, package statement, import statements, and a single top‑level class (or package‑info.java).

License/Header

If present, it must appear at the very top of the file.

Package statement

The package line is a single line and is exempt from the column‑limit rule.

Import statements

No wildcard imports (e.g., import java.util.*;).

One import per line; do not wrap.

Imports are grouped in this order, separated by a blank line between groups:

Static imports com.google imports (only when the file is under com.google)

Third‑party imports, alphabetically by top‑level package (android, com, junit, org, sun) java imports javax imports

Within a group no blank lines are allowed.

Class Declaration

Exactly one top‑level class per .java file (exception: package‑info.java which contains no class).

Members should be ordered logically; overloaded constructors or methods must appear together.

Declare one variable per statement and initialize it as soon as possible.

Formatting Rules

Braces : always present, even for single statements. Opening brace stays on the same line (K&R style); closing brace is on its own line.

Indentation : increase by two spaces for each new block level.

One statement per line : each statement ends with a line break.

Column limit : projects may choose 80 or 100 characters. Exceptions include long URLs in Javadoc, package / import lines, and shell‑command snippets in comments.

Automatic line wrapping : break at a higher syntactic level; break before non‑assignment operators, after assignment operators; continuation lines indented at least four spaces.

Blank lines : a single blank line separates logical groups of members, statements within a method, and may appear before the first or after the last member of a class.

Modifier order : follow the order recommended by the Java Language Specification (public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp).

Naming Conventions

General rules

Identifiers consist only of ASCII letters and digits ( \w+). Google‑specific prefixes/suffixes such as mName, kName, name_, s_name are not used.

Specific identifier types

Package names: all lower‑case, concatenated without underscores.

Class and interface names: UpperCamelCase; test classes end with Test (e.g., HashTest).

Method names: lowerCamelCase, usually verbs or verb phrases. JUnit test methods may contain underscores to separate logical parts.

Constant names: UPPER_CASE with underscores; only static final fields that are truly immutable qualify.

Non‑constant fields: lowerCamelCase.

Parameter names: lowerCamelCase; avoid single‑character names except for temporary or loop variables.

Local variable names: lowerCamelCase; abbreviations allowed but single‑character names discouraged.

Type variable names: either a single capital letter (optionally followed by a digit) or a class‑style name ending with T (e.g., RequestT).

CamelCase conversion

Convert prose to ASCII, split on spaces or punctuation, lowercase everything, then capitalize the first letter of each word for UpperCamelCase or all but the first word for lowerCamelCase. Examples:

"XML HTTP request" → XmlHttpRequest (preferred) or XMLHTTPRequest "new customer ID" → newCustomerId (preferred) or newCustomerID "supports IPv6 on iOS?" → supportsIpv6OnIos (preferred) or

supportsIPv6OnIOS

Programming Practices

Apply @Override to any method that overrides a superclass method.

Never silently ignore caught exceptions; log them, re‑throw as AssertionError, or add a comment explaining why no action is needed. In tests, an expected exception variable may be ignored.

Call static members via the class name ( Foo.staticMethod()) rather than through an instance or expression.

Do not override Object.finalize(). If finalization is ever required, read Effective Java §7 first.

Javadoc

Formatting

Standard block form:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally.
 */
public int method(String p1) { ... }

A single‑line form may be used for very short comments.

Paragraphs

Separate paragraphs with a blank line. Every paragraph after the first starts with <p> without a preceding space.

Tag order

When present, tags appear in the order @param, @return, @throws, @deprecated. Descriptions must not be empty; continuation lines are indented at least four spaces.

Summary sentence

Each class or member begins with a brief summary fragment (typically a noun or verb phrase, not a full sentence).

When Javadoc is required

All public classes and their public or protected members must have Javadoc, except for obvious getters/setters, overridden methods, and package‑private APIs unless additional context is needed.