From cbc2e018266428c6f696f702672f22bdf2f5adbc Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Mon, 1 Jul 2024 15:07:32 -0400 Subject: [PATCH] java: update to latest Pull in changes: * improve Egyptian brackets link * Add a note about JEP421 to #s6.4-finalizers * Fix broken link in java-style * Adding special camel case where word begins with number * Found an unclosed tag * Change ` tag around sort_java_imports * Clarify guidance on java vs javatests PiperOrigin-RevId: 648433358 --- javaguide.html | 132 +++++++++++++++++++++++++------------------------ 1 file changed, 68 insertions(+), 64 deletions(-) diff --git a/javaguide.html b/javaguide.html index 7467bef..0c73e7e 100644 --- a/javaguide.html +++ b/javaguide.html @@ -1,26 +1,28 @@ - + - + Google Java Style Guide - - - + + +

Google Java Style Guide

-
+

1 Introduction

This document serves as the complete definition of Google's coding standards for -source code in the Java™ Programming Language. A Java source file is described as being in +source code in the Java™ Programming Language. A Java source file is described as being in Google Style if and only if it adheres to the rules herein.

+ +

Like other programming style guides, the issues covered span not only aesthetic issues of formatting, but other types of conventions or coding standards as well. However, this document focuses primarily on the hard-and-fast rules that we follow universally, and @@ -29,6 +31,8 @@ avoids giving advice that isn't clearly enforceable (whether by human o + +

1.1 Terminology notes

In this document, unless otherwise clarified:

@@ -94,14 +98,14 @@ anywhere in a source file. This implies that:

\' and \\), that sequence is used rather than the corresponding octal -(e.g. \012) or Unicode -(e.g. \u000a) escape.

+(e.g. \012) or Unicode +(e.g. \u000a) escape.

2.3.3 Non-ASCII characters

For the remaining non-ASCII characters, either the actual Unicode character -(e.g. ∞) or the equivalent Unicode escape -(e.g. \u221e) is used. The choice depends only on +(e.g. ∞) or the equivalent Unicode escape +(e.g. \u221e) is used. The choice depends only on which makes the code easier to read and understand, although Unicode escapes outside string literals and comments are strongly discouraged.

@@ -117,12 +121,12 @@ Unicode characters are used, an explanatory comment can be very helpful.

- String unitAbbrev = "μs"; + String unitAbbrev = "μs"; Best: perfectly clear even without a comment. - String unitAbbrev = "\u03bcs"; // "μs" + String unitAbbrev = "\u03bcs"; // "μs" Allowed, but there's no reason to do this. @@ -149,7 +153,7 @@ some programs might not handle non-ASCII characters properly. If that should hap programs are broken and they must be fixed.

- +

3 Source file structure

@@ -176,7 +180,7 @@ programs are broken and they must be fixed.

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

- +

3.3 Import statements

3.3.1 No wildcard imports

@@ -214,12 +218,12 @@ normal imports.

3.4 Class declaration

- +

3.4.1 Exactly one top-level class declaration

Each top-level class resides in a source file of its own.

- +

3.4.2 Ordering of class contents

The order you choose for the members and initializers of your class can have a great effect on @@ -233,7 +237,7 @@ 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 @@ -248,7 +252,7 @@ the body of a class, method or constructor. 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.

- +

4.1 Braces

4.1.1 Use of optional braces

@@ -266,7 +270,7 @@ 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") +("Egyptian brackets") for nonempty blocks and block-like constructs:

    @@ -319,7 +323,7 @@ return new MyClass() {

    A few exceptions for enum classes are given in Section 4.8.1, Enum classes.

    - +

    4.1.3 Empty blocks: may be concise

    An empty block or block-like construct may be in K & R style (as described in @@ -356,7 +360,7 @@ applies to both code and comments throughout the block. (See the example in Sect

    Each statement is followed by a line break.

    - +

    4.4 Column limit: 100

    Java code has a column limit of 100 characters. A "character" means any Unicode code point. @@ -461,7 +465,7 @@ Predicate<String> predicate = str ->

    Note: The primary goal for line wrapping is to have clear code, not necessarily code that fits in the smallest number of lines.

    - +

    4.5.2 Indent continuation lines at least +4 spaces

    When line-wrapping, each line after the first (each continuation line) is indented @@ -602,15 +606,15 @@ private int x; // permitted, but future edits private Color color; // may leave it unaligned -

    Tip: Alignment can aid readability, but it creates problems for -future maintenance. Consider a future change that needs to touch just one line. This change may -leave the formerly-pleasing formatting mangled, and that is allowed. More often -it prompts the coder (perhaps you) to adjust whitespace on nearby lines as well, possibly -triggering a cascading series of reformattings. That one-line change now has a "blast radius." -This can at worst result in pointless busywork, but at best it still corrupts version history -information, slows down reviewers and exacerbates merge conflicts.

    +

    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 +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.

    - +

    4.7 Grouping parentheses: recommended

    Optional grouping parentheses are omitted only when author and reviewer agree that there is no @@ -646,7 +650,7 @@ as if it were an array initializer (see Section 4.8.3.1 on

    Since enum classes are classes, all other rules for formatting classes apply.

    - +

    4.8.2 Variable declarations

    4.8.2.1 One variable per declaration
    @@ -707,7 +711,7 @@ the last statement group, zero or more statements).

    as if a block were being opened. The following switch label returns to the previous indentation level, as if a block had been closed.

    - +
    4.8.4.2 Fall-through: commented

    Within a switch block, each statement group either terminates abruptly (with a @@ -747,7 +751,7 @@ analysis tools to issue a warning if any cases were missed.

    - +

    4.8.5 Annotations

    4.8.5.1 Type-use annotations
    @@ -804,7 +808,7 @@ for example:

    There are no specific rules for formatting annotations on parameters or local variables (except, of course, when the annotation is a type-use annotation).

    - +

    4.8.6 Comments

    This section addresses implementation comments. Javadoc is addressed separately in @@ -835,9 +839,9 @@ Such a comment renders the line non-blank.

    re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in // ... style comment blocks.

    - - + +

    4.8.7 Modifiers

    Class and member modifiers, when present, appear in the order @@ -853,7 +857,7 @@ recommended by the Java Language Specification: lowercase (to avoid confusion with the digit 1). For example, 3000000000L rather than 3000000000l.

    - +

    5 Naming

    5.1 Rules common to all identifiers

    @@ -866,6 +870,8 @@ underscores. Thus each valid identifier name is matched by the regular expressio names are not Google Style: name_, mName, s_name and kName.

    + +

    5.2 Rules by identifier type

    5.2.1 Package names

    @@ -907,7 +913,7 @@ name, with each component written in lowerCa example transferMoney_deductsFromSource. There is no One Correct Way to name test methods.

    -     +

    5.2.4 Constant names

    Constant names use UPPER_SNAKE_CASE: all uppercase @@ -978,8 +984,8 @@ be styled as constants.

    FooBarT).
- - + +

5.3 Camel case: defined

Sometimes there is more than one reasonable way to convert an English phrase into camel case, @@ -989,7 +995,7 @@ predictability, Google Style specifies the following (nearly) deterministic sche

Beginning with the prose form of the name:

    -
  1. Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's +
  2. Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's algorithm" might become "Muellers algorithm".
  3. Divide this result into words, splitting on spaces and any remaining punctuation (typically @@ -997,7 +1003,7 @@ predictability, Google Style specifies the following (nearly) deterministic sche
    • Recommended: if any word already has a conventional camel-case appearance in common - usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note + usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note that a word such as "iOS" is not really in camel case per se; it defies any convention, so this recommendation does not apply.
    @@ -1048,6 +1054,11 @@ predictability, Google Style specifies the following (nearly) deterministic sche YoutubeImporter* + + "Turn on 2SV" + turnOn2sv + turnOn2Sv +

    *Acceptable, but not recommended.

    @@ -1071,7 +1082,7 @@ method.

    @Override may be omitted when the parent method is @Deprecated.

    - +

    6.2 Caught exceptions: not ignored

    Except as noted below, it is very rarely correct to do nothing in response to a caught @@ -1113,21 +1124,14 @@ Foo.aStaticMethod(); // good somethingThatYieldsAFoo().aStaticMethod(); // very bad - +

    6.4 Finalizers: not used

    -

    It is extremely rare to override Object.finalize.

    - -

    Tip: Don't do it. If you absolutely must, first read and understand +

    Do not override Object.finalize. Finalization support +is scheduled for removal.

    - Effective Java Item 8, - -"Avoid finalizers and cleaners" very carefully, and then don't do it.

    - - - +

    7 Javadoc

    @@ -1152,9 +1156,9 @@ public int method(String p1) { ... }

    The basic form is always acceptable. The single-line form may be substituted when the entirety of the Javadoc block (including comment markers) can fit on a single line. Note that this only -applies when there are no block tags such as @return. +applies when there are no block tags such as @return.

    -

    7.1.2 Paragraphs

    +

    7.1.2 Paragraphs

    One blank line—that is, a line containing only the aligned leading asterisk (*)—appears between paragraphs, and before the group of block tags if present. @@ -1162,9 +1166,9 @@ Each paragraph except the first has <p> immediately before th no space after it. HTML tags for other block-level elements, such as <ul> or <table>, are not preceded with <p>.

    - + -

    7.1.3 Block tags

    +

    7.1.3 Block tags

    Any of the standard "block tags" that are used appear in the order @param, @return, @throws, @deprecated, and these four types never @@ -1178,7 +1182,7 @@ are indented four (or more) spaces from the position of the @. fragment is very important: it is the only part of the text that appears in certain contexts such as class and method indexes.

    -

    This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does +

    This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does not begin with A {@code Foo} is a..., or This method returns..., nor does it form a complete imperative sentence like Save the record.. However, the fragment is capitalized and @@ -1189,7 +1193,7 @@ punctuated as if it were a complete sentence.

    incorrect, and should be changed to /** Returns the customer ID. */.

    - +

    7.3 Where Javadoc is used

    At the minimum, Javadoc is present for every @@ -1232,9 +1236,9 @@ class or member, that comment is written as Javadoc instead (using /**Non-required Javadoc is not strictly required to follow the formatting rules of Sections 7.1.1, 7.1.2, 7.1.3, and 7.2, though it is of course recommended.

    - -
+ +
- + \ No newline at end of file