Google Java Style Guide

1. Introduction

• This document outlines Google’s coding standards for Java.
• Focus on enforceable rules over advisory suggestions.

1.1 Terminology Notes

• Class encompasses ordinary classes, record classes, enums, interfaces, and annotation types.
• Member includes nested classes, fields, methods, and constructors.
• Comment refers to implementation comments only, not documentation comments.

1.2 Guide Notes

• Example code is non-normative; other stylish formats exist.

2. Source File Basics

2.1 File Name

• Java source file name is the same as the top-level class name with .java extension.

2.2 File Encoding

• Use UTF-8 encoding for source files.

2.3 Special Characters

2.3.1 Whitespace Characters

• Only ASCII horizontal space character (0x20) is used.
• Tabs are not used for indentation.

2.3.2 Special Escape Sequences

• Use specific escape sequences (e.g., \n, \t) instead of octal or Unicode escapes.

2.3.3 Non-ASCII Characters

• Use Unicode characters or escapes based on readability.
• Avoid using Unicode escapes outside of string literals and comments.

3. Source File Structure

• Structure: license/copyright, package, imports, top-level class.

3.1 Copyright Information

• Placed at the top if present.

3.2 Package Statement

• No line-wrapping; column limit does not apply.

3.3 Import Statements

• No wildcard imports.
• Ordered in static and non-static blocks, sorted ASCII-wise.

3.4 Class Declaration

3.4.1 Top-level Class Declaration

• One top-level class per file.

3.4.2 Ordering of Class Contents

• Use logical ordering for members.

3.5 Module Declaration

• Directives ordered in specific blocks: requires, exports, opens, uses, provides.

4. Formatting

4.1 Braces

• Use braces with control statements even for single statements.
• Follow K&R style for non-empty blocks.

4.2 Block Indentation

• Indentation increases by 2 spaces for new blocks.

4.3 One Statement per Line

• Each statement ends with a line break.

4.4 Column Limit

• Limit of 100 characters, except for certain exceptions.

4.5 Line-Wrapping

• Break lines at higher syntactic levels.
• Continuation lines indented at least +4 spaces.

4.6 Whitespace

• One blank line between class members.
• Spaces around operators and reserved words.

4.7 Grouping Parentheses

• Recommended to avoid misinterpretation.

4.8 Specific Constructs

Enum Classes, Variable Declarations, Arrays

• Enum classes follow class rules.
• One variable per declaration unless in for loop.
• Arrays have specific initializer formatting rules.

4.8.4 Switch Statements

• Exhaustiveness required; use comments for fall-through in old-style switches.

4.8.5 Annotations

• Type-use annotations proceed the type. Class/package/module annotations appear after Javadoc.

5. Naming

5.1 Identifier Rules

• Use ASCII letters/digits; no special prefixes/suffixes.

5.2 Identifier Types

• Naming conventions for packages, classes, methods, constants, fields, and variables.
• Follow specified camel-case rules.

6. Programming Practices

6.1 @Override

• Always used unless the parent method is deprecated.

6.2 Caught Exceptions

• Exceptions should be handled or justified if ignored.

6.3 Static Members

• Access with class name, not instance.

6.4 Finalizers

• Do not use; scheduled for removal.

7. Javadoc

7.1 Formatting

• Basic form and single-line Javadoc.

7.2 Summary Fragment

• Begins Javadoc block; not a complete sentence.

7.3 Where Javadoc is Used

• Required for visible classes/members; exceptions for obvious members and overrides.