diff --git a/javaguide.html b/javaguide.html index aba8487..d6f54bf 100644 --- a/javaguide.html +++ b/javaguide.html @@ -14,7 +14,6 @@
-

1 Introduction

This document serves as the complete definition of Google's coding standards for @@ -38,12 +37,11 @@ avoids giving advice that isn't clearly enforceable (whether by human o

In this document, unless otherwise clarified:

    -
  1. The term class is used inclusively to mean an "ordinary" class, record class, enum +
  2. The term class is used inclusively to mean a normal class, record class, enum class, interface or annotation type (@interface).
  3. The term member (of a class) is used inclusively to mean a nested class, field, - method, or constructor; that is, all top-level contents of a class except initializers - and comments. + method, or constructor; that is, all top-level contents of a class except initializers.
  4. The term comment always refers to implementation comments. We do not use the phrase "documentation comments", and instead use the common term "Javadoc."
    5. @@ -79,7 +77,8 @@ character (0x20) is the only whitespace character that anywhere in a source file. This implies that:

      -
    1. All other whitespace characters in string and character literals are escaped.
      2. +
    2. All other whitespace characters are escaped in char and string literals and in + text blocks.
    3. Tab characters are not used for indentation.
    @@ -158,22 +157,22 @@ programs are broken and they must be fixed.

    3 Source file structure
    -

    An ordinary source file consists of, in order:

    +

    An ordinary source file consists of these sections, in order:

    1. License or copyright information, if present
      2. -
    2. Package statement
      3. -
    3. Import statements
      4. -
    4. Exactly one top-level class
      5. +
    5. Package declaration
      6. +
    6. Imports
      7. +
    7. Exactly one top-level class declaration

    Exactly one blank line separates each section that is present.

    -

    A package-info.java file is the same, but without the top-level class.

    +

    A package-info.java file is the same, but without the class declaration.

    -

    A module-info.java file does not contain a package statement and replaces the -single top-level class with a module declaration, but otherwise follows the same structure.

    +

    A module-info.java file does not contain a package declaration and replaces the +class declaration with a module declaration, but otherwise follows the same structure.

    @@ -181,38 +180,39 @@ single top-level class with a module declaration, but otherwise follows the same -

    3.2 Package statement

    + +

    3.2 Package declaration

    -

    The package statement is not line-wrapped. The column limit (Section 4.4, -Column limit: 100) does not apply to package statements.

    +

    The package declaration is not line-wrapped. The column limit (Section 4.4, +Column limit: 100) does not apply to package declarations.

    -

    3.3 Import statements

    +

    3.3 Imports

    3.3.1 No wildcard imports

    -

    Wildcard imports, static or otherwise, are not used.

    +

    Wildcard ("on-demand") imports, static or otherwise, are not + used.

    3.3.2 No line-wrapping

    -

    Import statements are not line-wrapped. The column limit (Section 4.4, -Column limit: 100) does not apply to import -statements.

    +

    Imports are not line-wrapped. The column limit (Section 4.4, +Column limit: 100) does not apply to imports.

    3.3.3 Ordering and spacing

    Imports are ordered as follows:

      -
    1. All static imports in a single block.
      2. -
    2. All non-static imports in a single block.
      3. +
    3. All static imports in a single group.
      4. +
    4. All non-static imports in a single group.

    If there are both static and non-static imports, a single blank line separates the two -blocks. There are no other blank lines between import statements.

    +groups. There are no other blank lines between imports.

    -

    Within each block the imported names appear in ASCII sort order. (Note: -this is not the same as the import statements being in ASCII sort order, since '.' +

    Within each group the imported names appear in ASCII sort order. (Note: +this is not the same as the import lines being in ASCII sort order, since '.' sorts before ';'.)

    @@ -247,9 +247,9 @@ ordering.

    3.4.2.1 Overloads: never split

    Methods of a class that share the same name appear in a single contiguous group with no other -members in between. The same applies to multiple constructors (which always have the same name). -This rule applies even when modifiers such as static or -private differ between the methods.

    + members in between. The same applies to multiple constructors. This rule applies even when + modifiers such as static or + private differ between the methods or constructors.

    3.5 Module declaration

    @@ -270,7 +270,7 @@ This rule applies even when modifiers such as 4 Formatting

    Terminology Note: block-like construct refers to -the body of a class, method or constructor. Note that, by Section 4.8.3.1 on +the body of a class, method, constructor, or switch. Note that, by Section 4.8.3.1 on array initializers, any array initializer may optionally be treated as if it were a block-like construct.

    @@ -291,9 +291,8 @@ body is empty or contains only a single statement.

    4.1.2 Nonempty blocks: K & R style

    -

    Braces follow the Kernighan and Ritchie style -("Egyptian brackets") -for nonempty blocks and block-like constructs:

    +

    Braces follow the Kernighan and Ritchie style for nonempty blocks and block-like + constructs:

    • No line break before the opening brace, except as detailed below.
      • @@ -401,12 +400,11 @@ you may choose to wrap the line earlier than where this rule strictly requires.<
    • Lines where obeying the column limit is not possible (for example, a long URL in Javadoc, or a long JSNI method reference).
      • -
    • package and - import statements (see Sections - 3.2 Package statement and - 3.3 Import statements).
      • +
    • package declarations and + imports (see Sections 3.2 Package declarations and + 3.3 Imports).
      • -
    • Contents of text blocks.
      • +
    • Contents of text blocks.
    • Command lines in a comment that may be copied-and-pasted into a shell.
      • @@ -420,7 +418,7 @@ you may choose to wrap the line earlier than where this rule strictly requires.<

      4.5 Line-wrapping

      -

      Terminology Note: When code that might otherwise legally +

      Terminology Note: When code that might otherwise occupy a single line is divided into multiple lines, this activity is called line-wrapping.

      @@ -461,7 +459,7 @@ without the need to line-wrap.

    • When a line is broken at an assignment operator the break typically comes after the symbol, but either way is acceptable.
        -
      • This also applies to the "assignment-operator-like" colon in an enhanced +
      • This also applies to the colon in an enhanced for ("foreach") statement.
      • @@ -511,7 +509,7 @@ previous lines.

      4.6 Whitespace

      -

      4.6.1 Vertical Whitespace

      +

      4.6.1 Vertical whitespace (blank lines)

      A single blank line always appears:

      @@ -529,7 +527,7 @@ previous lines.

    • As required by other sections of this document (such as Section 3, Source file structure, and Section 3.3, - Import statements).
      • + Imports).

A single blank line may also appear anywhere it improves readability, for example between @@ -541,18 +539,19 @@ discouraged.

4.6.2 Horizontal whitespace

-

Beyond where required by the language or other style rules, and apart from literals, comments and -Javadoc, a single ASCII space also appears in the following places only.

+

Beyond where required by the language or other style rules, and apart from within literals, +comments and Javadoc, a single ASCII space also appears in the following places +only.

    -
  1. Separating any reserved word, such as +
  2. Separating any keyword, such as if, for or catch, from an open parenthesis (() that follows it on that line
    3. -
  3. Separating any reserved word, such as +
  4. Separating any keyword, such as else or catch, from a closing curly brace (}) that precedes it on that line
    5. @@ -563,14 +562,14 @@ Javadoc, a single ASCII space also appears in the following places only<
  5. @SomeAnnotation({a, b}) (no space is used)
  6. String[][] x = {{"foo"}}; (no space is required - between {{, by item 9 below)
    7. + between {{, by item 10 below)
  7. On both sides of any binary or ternary operator. This also applies to the following "operator-like" symbols:
      -
    • the ampersand in a conjunctive type bound: +
    • the ampersand that separates multiple type bounds: <T extends Foo & Bar>
    • the pipe for a catch block that handles multiple exceptions: @@ -603,7 +602,7 @@ Javadoc, a single ASCII space also appears in the following places only<
    • Between a double slash (//) which begins a comment and the comment's text. Multiple spaces are allowed.
      • -
    • Between the type and variable of a declaration: +
    • Between the type and identifier of a declaration: List<String> list
    • Optional just inside both braces of an array initializer @@ -638,13 +637,12 @@ private int x; // permitted, but future edits private Color color; // may leave it unaligned -

      Tip: Alignment can aid readability, but attempts to preserve -alignment for its own sake create future problems. For example, consider a change that touches only +

      Tip: Alignment can aid readability, but attempting to preserve +alignment for its own sake creates future problems. For example, consider a change that touches only one line. If that change disrupts the previous alignment, it's important **not** to introduce additional changes on nearby lines simply to realign them. Introducing formatting changes on otherwise unaffected lines corrupts version history, slows down reviewers, and exacerbates merge -conflicts. These practical concerns -take priority over alignment.

      +conflicts. These practical concerns take priority over alignment.

      4.7 Grouping parentheses: recommended

      @@ -658,7 +656,7 @@ operator precedence table memorized.

      4.8.1 Enum classes

      -

      After each comma that follows an enum constant, a line break is optional. Additional blank +

      After the comma that follows an enum constant, a line break is optional. Additional blank lines (usually just one) are also allowed. This is one possibility: 

      private enum Answer {
@@ -770,7 +768,7 @@ switch label.

      In an old-style switch, the colon of each switch label is followed by a line break. The -statements within a statement group start with a further +2 indentation.

      +statements within a statement group are indented a further +2.

      4.8.4.2 Fall-through: commented