From 49488412b2f59843fce2433bd834a3fd9700604e Mon Sep 17 00:00:00 2001 From: Liam Miller-Cushon Date: Wed, 2 Feb 2022 19:31:16 -0800 Subject: [PATCH] Update Java style guide --- javaguide.html | 144 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 98 insertions(+), 46 deletions(-) diff --git a/javaguide.html b/javaguide.html index bbdbc1c92..de177873e 100644 --- a/javaguide.html +++ b/javaguide.html @@ -42,7 +42,7 @@

1.1 Terminology notes

and comments.
  • The term comment always refers to implementation comments. We do not - use the phrase "documentation comments", instead using the common term "Javadoc."
    • + use the phrase "documentation comments", and instead use the common term "Javadoc."

    Other "terminology notes" will appear occasionally throughout the document.

    @@ -236,8 +236,10 @@

    3.4.2 Ordering of class contents

    3.4.2.1 Overloads: never split
    -

    When a class has multiple constructors, or multiple methods with the same name, these appear -sequentially, with no other code in between (not even private members).

    +

    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.

    4 Formatting

    @@ -249,7 +251,7 @@

    4 Formatting

    4.1 Braces

    -

    4.1.1 Braces are used where optional

    +

    4.1.1 Use of optional braces

    Braces are used with if, @@ -259,6 +261,8 @@

    4.1.1 Braces are used where optional

    while statements, even when the body is empty or contains only a single statement.

    +

    Other optional braces, such as those in a lambda expression, remain optional.

    +

    4.1.2 Nonempty blocks: K & R style

    Braces follow the Kernighan and Ritchie style @@ -266,7 +270,7 @@

    4.1.2 Nonempty blocks: K & R style

    for nonempty blocks and block-like constructs:

    +

    Exception: In places where these rules allow a single statement ending with a semicolon +(;), a block of statements can appear, and the opening +brace of this block is preceded by a line break. Blocks like these are typically introduced to +limit the scope of local variables, for example inside switch statements.

    +

    Examples:

    return () -> {
@@ -299,6 +308,10 @@ 
    4.1.2 Nonempty blocks: K & R style
    
     } else {
       lastThing();
     }
+    {
+      int x = foo();
+      frob(x);
+    }
   }
 };
    @@ -367,7 +380,14 @@

    4.4 Column limit: 100

    3.2 Package statement and 3.3 Import statements). -
  • Command lines in a comment that may be cut-and-pasted into a shell.
    • +
  • Command lines in a comment that may be copied-and-pasted into a shell.
    • + +
  • Very long identifiers, on the rare occasions they are called for, are allowed to exceed the + column limit. In that case, the valid wrapping for the surrounding code is as produced by + + + google-java-format. +

    • 4.5 Line-wrapping

    @@ -509,7 +529,7 @@

    4.6.2 Horizontal whitespace

  • @SomeAnnotation({a, b}) (no space is used)
  • String[][] x = {{"foo"}}; (no space is required - between {{, by item 8 below)
    • + between {{, by item 9 below) @@ -541,8 +561,11 @@

    4.6.2 Horizontal whitespace

  • After ,:; or the closing parenthesis ()) of a cast
    • -
  • On both sides of the double slash (//) that - begins an end-of-line comment. Here, multiple spaces are allowed, but not required.
    • +
  • Between any content and a double slash (//) which + begins a comment. Multiple spaces are allowed.
    • + +
  • 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: List<String> list
    • @@ -712,7 +735,7 @@
    4.8.4.2 Fall-through: commented

    Notice that no comment is needed after case 1:, only at the end of the statement group.

    -
    4.8.4.3 The default case is present
    +
    4.8.4.3 Presence of the default label

    Each switch statement includes a default statement group, even if it contains no code.

    @@ -727,14 +750,37 @@
    4.8.4.3 The default case is presen

    4.8.5 Annotations

    -

    Annotations applying to a class, method or constructor appear immediately after the +

    4.8.5.1 Type-use annotations
    + +

    Type-use annotations appear immediately before the annotated type. An annotation is a type-use +annotation if it is meta-annotated with +@Target(ElementType.TYPE_USE). Example:

    + +
    final @Nullable String name;
+
+public @Nullable Person getPersonByName(String name);
+
    + +
    4.8.5.2 Class annotations
    + +

    Annotations applying to a class appear immediately after the documentation block, and each annotation is listed on a line of its own (that is, one annotation per line). These line breaks do not constitute line-wrapping (Section 4.5, Line-wrapping), so the indentation level is not increased. Example:

    -
    @Override
-@Nullable
+
    @Deprecated
+@CheckReturnValue
+public final class Frozzler { ... }
+
    
+
+
    4.8.5.3 Method and constructor annotations
    
+
+
    The rules for annotations on method and constructor declarations are the same as the
+previous section. Example: 
    
+
+
    @Deprecated
+@Override
 public String getNameIfPresent() { ... }
 
    
 
@@ -744,6 +790,8 @@ 
    4.8.5 Annotations
    
 
    @Override public int hashCode() { ... }
 
    
 
+
    4.8.5.4 Field annotations
    
+
 
    Annotations applying to a field also appear immediately after the documentation block, but in
 this case, multiple annotations (possibly parameterized) may be listed on the same line;
 for example:
    
@@ -751,8 +799,10 @@ 
    4.8.5 Annotations
    
 
    @Partial @Mock DataLoader loader;
 
    
 
-
    There are no specific rules for formatting annotations on parameters, local variables, or types.
-
    
+
    4.8.5.5 Parameter and local variable annotations
    
+
+
    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
    
@@ -820,12 +870,12 @@ 
    5.2 Rules by identifier type
    
 
 
    5.2.1 Package names
    
 
-
    Package names are all lowercase, with consecutive words simply concatenated together (no
-underscores). For example, com.example.deepspace, not
+
    Package names use only lowercase letters and digits (no underscores). Consecutive words are
+simply concatenated together. For example, com.example.deepspace, not
 com.example.deepSpace or
-com.example.deep_space.
    
+com.example.deep_space.
 
-
    5.2.2 Class names
    
+
    5.2.2 Class names
    
 
 
    Class names are written in UpperCamelCase.
    
 
@@ -838,10 +888,11 @@ 
    5.2.2 Class names
    
 
 
    There are no specific rules or even well-established conventions for naming annotation types.
    
 
-
    Test classes are named starting with the name of the class they are testing, and ending
-with Test. For example,
-HashTest or
-HashIntegrationTest.
    
+
    A test class has a name that ends with Test,
+for example, HashIntegrationTest.
+If it covers a single class, its name is the name of that class
+plus Test, for example HashImplTest.
    
 
 
    5.2.3 Method names
    
 
@@ -852,30 +903,28 @@ 
    5.2.3 Method names
    
 stop.
    
 
 
    Underscores may appear in JUnit test method names to separate logical components of the
-name, with each component written in lowerCamelCase.
-One typical pattern is <methodUnderTest>_<state>,
-for example pop_emptyStack. There is no One Correct
-Way to name test methods.
    
+name, with each component written in lowerCamelCase, for
+example transferMoney_deductsFromSource. There is no One
+Correct Way to name test methods.
    
 
 
 
    5.2.4 Constant names
    
 
-
    Constant names use CONSTANT_CASE: all uppercase
+
    Constant names use UPPER_SNAKE_CASE: all uppercase
 letters, with each word separated from the next by a single underscore. But what is a
 constant, exactly?
    
 
 
    Constants are static final fields whose contents are deeply immutable and whose methods have no
-detectable side effects. This includes primitives, Strings, immutable types, and immutable
-collections of immutable types. If any of the instance's observable state can change, it is not a
+detectable side effects. Examples include primitives, strings, immutable value classes, and anything
+set to null. If any of the instance's observable state can change, it is not a
 constant. Merely intending to never mutate the object is not enough. Examples:
    
 
 
    // Constants
 static final int NUMBER = 5;
 static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
-static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
+static final Map<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
 static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
 static final SomeMutableType[] EMPTY_ARRAY = {};
-enum SomeEnum { ENUM_CONSTANT }
 
 // Not constants
 static String nonFinal = "non-final";
@@ -1073,9 +1122,9 @@ 
    6.4 Finalizers: not used
    
 
    Tip: Don't do it. If you absolutely must, first read and understand
 
 
-  Effective Java Item 7,
+  Effective Java Item 8,
 
-"Avoid Finalizers," very carefully, and then don't do it.
    
+"Avoid finalizers and cleaners" very carefully, and then don't do it.
    
 
 
 
@@ -1107,14 +1156,15 @@ 
    7.1.1 General form
    
 
 
    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. Each paragraph but the first has <p> immediately before the first word,
-with no space after.
    
+
    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.
+Each paragraph except the first has <p> immediately before the first word, with
+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
@@ -1135,8 +1185,9 @@ 
    7.2 The summary fragment
    
 punctuated as if it were a complete sentence.
    
 
 
    Tip: A common mistake is to write simple Javadoc in the form
-/** @return the customer ID */. This is incorrect, and should be
-changed to /** Returns the customer ID. */.
    
+/** @return the customer ID */. This is
+incorrect, and should be changed to
+/** Returns the customer ID. */.
    
 
  
 
    7.3 Where Javadoc is used
    
@@ -1150,11 +1201,11 @@ 
    7.3 Where Javadoc is used
    
 
    Additional Javadoc content may also be present, as explained in Section 7.3.4,
 Non-required Javadoc.
    
 
-
    7.3.1 Exception: self-explanatory methods
    
+
    7.3.1 Exception: self-explanatory members
    
 
-
    Javadoc is optional for "simple, obvious" methods like
-getFoo, in cases where there really and truly is
-nothing else worthwhile to say but "Returns the foo".
    
+
    Javadoc is optional for "simple, obvious" members like
+getFoo(), in cases where there really and truly
+ is nothing else worthwhile to say but "Returns the foo".
    
 
 
    Important: it is not appropriate to cite this exception to justify
 omitting relevant information that a typical reader might need to know. For example, for a method
@@ -1179,7 +1230,7 @@ 
    7.3.4 Non-required Javadoc
    
 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.2, 7.1.3, and 7.2, though it is of course recommended.
    
+7.1.1, 7.1.2, 7.1.3, and 7.2, though it is of course recommended.
    
 
  
 
@@ -1187,3 +1238,4 @@ 
    7.3.4 Non-required Javadoc
    
 
 
 
+