| //// |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| https://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| //// |
| = Java Style Guidelines |
| |
| [#intro] |
| == Introduction |
| |
| This document serves as the *complete* definition of the Log4j project's |
| coding standards for source code in the Java™ Programming Language. It |
| originated from the Google coding standards but incorporates |
| modifications that reflect the desires of the Log4j community. |
| |
| 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 avoids giving |
| _advice_ that isn't clearly enforceable (whether by human or tool). |
| |
| [#terminology] |
| === Terminology notes |
| |
| In this document, unless otherwise clarified: |
| |
| 1. The term _class_ is used inclusively to mean an "ordinary" class, |
| enum class, interface or annotation type (`@interface`). |
| 2. The term _comment_ always refers to _implementation_ comments. We do |
| not use the phrase "documentation comments", instead using the common |
| term "Javadoc." |
| |
| Other "terminology notes" will appear occasionally throughout the |
| document. |
| |
| [#guide-notes] |
| === Guide notes |
| |
| Example code in this document is *non-normative*. That is, while the |
| examples are in Log4j Style, they may not illustrate the _only_ stylish |
| way to represent the code. Optional formatting choices made in examples |
| should not be enforced as rules. |
| |
| [#source-file-basics] |
| == Source File Basics |
| |
| [#file-name] |
| === File name |
| |
| The source file name consists of the case-sensitive name of the |
| top-level class it contains, plus the `.java` extension. |
| |
| [#file-encoding] |
| === File encoding: UTF-8 |
| |
| Source files are encoded in *UTF-8*. |
| |
| [#special-characters] |
| === Special characters |
| |
| [#whitespace-characters] |
| ==== Whitespace characters |
| |
| Aside from the line terminator sequence, the *ASCII horizontal space |
| character* (*0x20*) is the only whitespace character that appears |
| anywhere in a source file. This implies that: |
| |
| 1. All other whitespace characters in string and character literals are |
| escaped. |
| 2. Tab characters are *not* used for indentation. |
| |
| [#special-escape-sequences] |
| ==== Special escape sequences |
| |
| For any character that has a special escape sequence (`\b`, `\t`, `\n`, |
| `\f`, `\r`, `\"`, `\'` and `\\`), that sequence is used rather than the |
| corresponding octal (e.g. `\012`) or Unicode (e.g. `\u000a`) escape. |
| |
| [#non-ascii-characters] |
| ==== 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, depending only on which makes the code *easier to read and |
| understand*. |
| |
| TIP: In the Unicode escape case, and occasionally even when actual |
| Unicode characters are used, an explanatory comment can be very helpful. |
| |
| Examples: |
| |
| [cols=",",options="header",] |
| |======================================================================= |
| |Example |Discussion |
| |`String unitAbbrev = "μs";` |Best: perfectly clear even without a |
| comment. |
| |
| |`String unitAbbrev = "\u03bcs"; // "μs"` |Allowed, but there's no |
| reason to do this. |
| |
| |`String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"` |Allowed, but |
| awkward and prone to mistakes. |
| |
| |`String unitAbbrev = "\u03bcs";` |Poor: the reader has no idea what |
| this is. |
| |
| |`return '\ufeff' + content; // byte order mark` |Good: use escapes for |
| non-printable characters, and comment if necessary. |
| |======================================================================= |
| |
| TIP: Never make your code less readable simply out of fear that some |
| programs might not handle non-ASCII characters properly. If that should |
| happen, those programs are *broken* and they must be *fixed*. |
| |
| [#source-file-structure] |
| == Source File Structure |
| |
| [[filestructure]] |
| A source file consists of, *in order*: |
| |
| 1. Apache license |
| 2. Package statement |
| 3. Import statements |
| 4. Exactly one top-level class |
| |
| *Exactly one blank line* separates each section that is present. |
| |
| [#license] |
| === Apache License |
| |
| The Apache license belongs here. No other license should appear. Other |
| licenses that apply should be referenced in a NOTICE file |
| |
| [#package-statement] |
| === Package statement |
| |
| The package statement is *not line-wrapped*. The column limit |
| (<<column-limit>>) does not apply to package statements. |
| |
| [#import-statements] |
| === Import statements |
| |
| [[imports]] |
| |
| [#wildcard-imports] |
| ==== No wildcard imports in the main tree |
| |
| *Wildcard imports*, static or otherwise, *are not used*. |
| |
| [#static-wildcart-imports] |
| ==== Static wildcard imports in the test tree |
| |
| *Wildcard static imports* are encouraged for test imports like JUnit, |
| EasyMock, and Hamcrest. |
| |
| [#import-line-wrapping] |
| ==== No line-wrapping |
| |
| Import statements are *not line-wrapped*. The column limit |
| (<<column-limit>>) does not apply to import |
| statements. |
| |
| [#import-ordering-and-spacing] |
| ==== Ordering and spacing |
| |
| Import statements are divided into the following groups, in this order, |
| with each group separated by a single blank line: |
| |
| 1. java |
| 2. javax |
| 3. org |
| 4. com |
| 5. All static imports in a single group |
| |
| Within a group there are no blank lines, and the imported names appear |
| in ASCII sort order. (NOTE: this is not the same as the import |
| _statements_ being in ASCII sort order; the presence of semicolons warps |
| the result.) |
| |
| IDE settings for ordering imports automatically can be found in the |
| source distributions under `src/ide`. For example: |
| |
| * Eclipse: `src/ide/eclipse/4.3.2/organize-imports.importorder` |
| * IntelliJ: `src/ide/Intellij/13/IntellijSettings.jar` |
| |
| [#class-declaration] |
| === Class declaration |
| |
| [#one-top-level-class] |
| ==== Exactly one top-level class declaration |
| |
| [[oneclassperfile]] |
| Each top-level class resides in a source file of its own. |
| |
| [#class-member-ordering] |
| ==== Class member ordering |
| |
| Class members should be grouped in the following order>. |
| |
| . static variables grouped in the order shown below. Within a group |
| variables may appear in any order. |
| .. public |
| .. protected |
| .. package |
| .. private |
| . instance variables grouped in the order shown below. Within a group |
| variables may appear in any order |
| .. public |
| .. protected |
| .. package |
| .. private |
| .. constructors |
| . methods may be specified in the following order but may appear in |
| another order if it improves the clarity of the program. |
| .. public |
| .. protected |
| .. package |
| .. private |
| |
| [[overloads]] [[never-split]] |
| Overloads: never split |
| |
| When a class has multiple constructors, or multiple methods with the |
| same name, these appear sequentially, with no intervening members. |
| |
| [#formatting] |
| == Formatting |
| |
| [NOTE] |
| ==== |
| _block-like construct_ refers to the body of a |
| class, method or constructor. Note that, by |
| link:#array-initializers[array initializers], any array initializer _may_ |
| optionally be treated as if it were a block-like construct. |
| ==== |
| |
| [#braces] |
| === Braces |
| |
| [#braces-always-used] |
| ==== Braces are used where optional |
| |
| Braces are used with `if`, `else`, `for`, `do` and `while` statements, |
| even when the body is empty or contains only a single statement. |
| |
| [#blocks-k-r-style] |
| ==== Nonempty blocks: K & R style |
| |
| Braces follow the Kernighan and Ritchie style |
| ("http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html[Egyptian |
| brackets]") for _nonempty_ blocks and block-like constructs: |
| |
| * No line break before the opening brace. |
| * Line break after the opening brace. |
| * Line break before the closing brace. |
| * Line break after the closing brace _if_ that brace terminates a |
| statement or the body of a method, constructor or _named_ class. For |
| example, there is _no_ line break after the brace if it is followed by |
| `else` or a comma. |
| |
| Example: |
| |
| [source,java] |
| ---- |
| return new MyClass() { |
| @Override public void method() { |
| if (condition()) { |
| try { |
| something(); |
| } catch (ProblemException e) { |
| recover(); |
| } |
| } |
| } |
| }; |
| ---- |
| |
| A few exceptions for enum classes are given in <<enum-classes>>. |
| |
| |
| [#braces-empty-blocks] |
| ==== Empty blocks: may be concise |
| |
| [[emptyblocks]] |
| An empty block or block-like construct _may_ be closed immediately after |
| it is opened, with no characters or line break in between (`{}`), |
| *unless* it is part of a _multi-block statement_ (one that directly |
| contains multiple blocks: `if/else-if/else` or `try/catch/finally`). |
| |
| Example: |
| |
| [source,java] |
| ---- |
| void doNothing() {} |
| ---- |
| |
| [#block-indentation] |
| === Block indentation: +4 spaces |
| |
| Each time a new block or block-like construct is opened, the indent |
| increases by four spaces. When the block ends, the indent returns to the |
| previous indent level. The indent level applies to both code and |
| comments throughout the block. (See the example in <<blocks-k-r-style>>.) |
| |
| [#one-statement-per-line] |
| === One statement per line |
| |
| Each statement is followed by a line-break. |
| |
| |
| [#column-limit] |
| === Column limit: 120 |
| |
| [[columnlimit]] |
| The column limit for Log4j is 120 characters. Except as noted below, any |
| line that would exceed this limit must be line-wrapped, as explained in |
| <<line-wrapping>>. |
| |
| *Exceptions:* |
| |
| 1. Lines where obeying the column limit is not possible (for example, a |
| long URL in Javadoc, or a long JSNI method reference). |
| 2. `package` and `import` statements (see |
| link:#package-statement[Package statement] and |
| link:#import-statements[Import statements]). |
| 3. Command lines in a comment that may be cut-and-pasted into a shell. |
| |
| [#line-wrapping] |
| === Line-wrapping |
| |
| *Terminology Note:* When code that might otherwise legally occupy a |
| single line is divided into multiple lines, typically to avoid |
| overflowing the column limit, this activity is called _line-wrapping_. |
| |
| There is no comprehensive, deterministic formula showing _exactly_ how |
| to line-wrap in every situation. Very often there are several valid ways |
| to line-wrap the same piece of code. |
| |
| TIP: Extracting a method or local variable may solve the problem |
| without the need to line-wrap. |
| |
| [#line-wrapping-where-to-break] |
| ==== Where to break |
| |
| The prime directive of line-wrapping is: prefer to break at a *higher |
| syntactic level*. Also: |
| |
| 1. When a line is broken at a _non-assignment_ operator the break comes |
| _before_ the symbol. (Note that this is not the same practice used in |
| Google style for other languages, such as C++ and JavaScript.) |
| * This also applies to the following "operator-like" symbols: the dot |
| separator (`.`), the ampersand in type bounds (`<T extends Foo & Bar>`), |
| and the pipe in catch blocks (`catch (FooException | BarException e)`). |
| 2. 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 `for` ("foreach") statement. |
| 3. A method or constructor name stays attached to the open parenthesis |
| (`(`) that follows it. |
| 4. A comma (`,`) stays attached to the token that precedes it. |
| |
| |
| [#line-wrapping-indent] |
| ==== Indent continuation lines at least +8 spaces |
| |
| [[indentation]] |
| When line-wrapping, each line after the first (each _continuation line_) |
| is indented at least +8 from the original line. |
| |
| When there are multiple continuation lines, indentation may be varied |
| beyond +8 as desired. In general, two continuation lines use the same |
| indentation level if and only if they begin with syntactically parallel |
| elements. |
| |
| The section on link:#horizontal-alignment[Horizontal alignment] |
| addresses the discouraged practice of using a variable number of spaces |
| to align certain tokens with previous lines. |
| |
| [#whitespace] |
| === Whitespace |
| |
| [#vertical-whitespace] |
| ==== Vertical Whitespace |
| |
| A single blank line appears: |
| |
| 1. _Between_ consecutive members (or initializers) of a class: fields, |
| constructors, methods, nested classes, static initializers, instance |
| initializers. |
| * *Exception:* A blank line between two consecutive fields (having no |
| other code between them) is optional. Such blank lines are used as |
| needed to create _logical groupings_ of fields. |
| 2. Within method bodies, as needed to create _logical groupings_ of |
| statements. |
| 3. _Optionally_ before the first member or after the last member of the |
| class (neither encouraged nor discouraged). |
| 4. As required by other sections of this document (such as |
| <<import-statements>>). |
| |
| _Multiple_ consecutive blank lines are permitted, but never required (or |
| encouraged). |
| |
| [#horizontal-whitespace] |
| ==== 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*. |
| |
| 1. Separating any reserved word, such as `if`, `for` or `catch`, from |
| an open parenthesis (`(`) that follows it on that line |
| 2. Separating any reserved word, such as `else` or `catch`, from a |
| closing curly brace (`}`) that precedes it on that line |
| 3. Before any open curly brace (`{`), with two exceptions: |
| * `String[][] x = {{"foo"}};` (no space is required between `{{`, by |
| item 8 below) |
| 4. 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: `<T extends Foo & Bar>` |
| * the pipe for a catch block that handles multiple exceptions: |
| `catch (FooException | BarException e)` |
| * the colon (`:`) in an enhanced `for` ("foreach") statement |
| 5. After `,:;` or the closing parenthesis (`)`) of a cast |
| 6. On both sides of the double slash (`//`) that begins an end-of-line |
| comment. Here, multiple spaces are allowed, but not required. |
| 7. Between the type and variable of a declaration: `List<String> list` |
| 8. _Optional_ just inside both braces of an array initializer |
| * `new int[] {5, 6}` and `new int[] { 5, 6 }` are both valid |
| |
| NOTE: This rule never requires or forbids additional space at the |
| start or end of a line, only _interior_ space. |
| |
| [#horizontal-alignment] |
| ==== Horizontal alignment: never required |
| |
| *Terminology Note:* _Horizontal alignment_ is the practice of adding a |
| variable number of additional spaces in your code with the goal of |
| making certain tokens appear directly below certain other tokens on |
| previous lines. |
| |
| This practice is permitted, but is *never required* by Google Style. It |
| is not even required to _maintain_ horizontal alignment in places where |
| it was already used. |
| |
| Here is an example without alignment, then using alignment: |
| |
| [source,java] |
| ---- |
| private int x; // this is fine |
| private Color color; // this too |
| |
| 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. |
| |
| [#grouping-parentheses] |
| === Grouping parentheses: recommended |
| |
| [[parentheses]] |
| Optional grouping parentheses are omitted only when author and reviewer |
| agree that there is no reasonable chance the code will be misinterpreted |
| without them, nor would they have made the code easier to read. It is |
| _not_ reasonable to assume that every reader has the entire Java |
| operator precedence table memorized. |
| |
| [#specific-constructs] |
| === Specific constructs |
| |
| [#enum-classes] |
| ==== Enum classes |
| |
| After each comma that follows an enum constant, a line-break is |
| optional. |
| |
| An enum class with no methods and no documentation on its constants may |
| optionally be formatted as if it were an array initializer (see |
| link:array-initializers[array initializers]). |
| |
| [source,java] |
| ---- |
| private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS } |
| ---- |
| |
| Since enum classes _are classes_, all other rules for formatting classes |
| apply. |
| |
| [#variable-declarations] |
| ==== Variable declarations |
| |
| [[localvariables]] |
| [[variables-per-declaration]] |
| One variable per declaration |
| |
| Every variable declaration (field or local) declares only one variable: |
| declarations such as `int a, b;` are not used. |
| |
| [[variables-limited-scope]] |
| Declared when needed, initialized as soon as possible |
| |
| Local variables are *not* habitually declared at the start of their |
| containing block or block-like construct. Instead, local variables are |
| declared close to the point they are first used (within reason), to |
| minimize their scope. Local variable declarations typically have |
| initializers, or are initialized immediately after declaration. |
| |
| [#s4.8.3-arrays] |
| ==== Arrays |
| |
| [[array-initializers]] |
| Array initializers: can be "block-like" |
| |
| Any array initializer may _optionally_ be formatted as if it were a |
| "block-like construct." For example, the following are all valid (*not* |
| an exhaustive list): |
| |
| [source,java] |
| ---- |
| new int[] { new int[] { |
| 0, 1, 2, 3 0, |
| } 1, |
| 2, |
| new int[] { 3, |
| 0, 1, } |
| 2, 3 |
| } new int[] |
| {0, 1, 2, 3} |
| ---- |
| |
| [[array-declarations]] |
| No C-style array declarations |
| |
| The square brackets form a part of the _type_, not the variable: |
| `String[] args`, not `String args[]`. |
| |
| [#switch] |
| ==== Switch statements |
| |
| *Terminology Note:* Inside the braces of a _switch block_ are one or |
| more _statement groups_. Each statement group consists of one or more |
| _switch labels_ (either `case FOO:` or `default:`), followed by one or |
| more statements. |
| |
| [[switch-indentation]] |
| ===== Indentation |
| |
| As with any other block, the contents of a switch block are indented +2. |
| |
| After a switch label, a newline appears, and the indentation level is |
| increased +2, exactly as if a block were being opened. The following |
| switch label returns to the previous indentation level, as if a block |
| had been closed. |
| |
| [#switch-fall-through] |
| ===== Fall-through: commented |
| |
| [[fallthrough]] |
| Within a switch block, each statement group either terminates abruptly |
| (with a `break`, `continue`, `return` or thrown exception), or is marked |
| with a comment to indicate that execution will or _might_ continue into |
| the next statement group. Any comment that communicates the idea of |
| fall-through is sufficient (typically `// fall through`). This special |
| comment is not required in the last statement group of the switch block. |
| Example: |
| |
| [source,java] |
| ---- |
| switch (input) { |
| case 1: |
| case 2: |
| prepareOneOrTwo(); |
| // fall through |
| case 3: |
| handleOneTwoOrThree(); |
| break; |
| default: |
| handleLargeNumber(input); |
| } |
| ---- |
| |
| [[switch-default]] |
| The default case is present. |
| |
| Each switch statement includes a `default` statement group, even if it |
| contains no code. |
| |
| [#annotations] |
| ==== Annotations |
| |
| Annotations applying to a class, method or constructor 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, |
| link:#line-wrapping[Line-wrapping]), so the indentation level is not |
| increased. Example: |
| |
| [source,java] |
| ---- |
| @Override |
| @Nullable |
| public String getNameIfPresent() { ... } |
| ---- |
| |
| *Exception:* A _single_ parameterless annotation _may_ instead appear |
| together with the first line of the signature, for example: |
| |
| [source,java] |
| ---- |
| @Override public int hashCode() { ... } |
| ---- |
| |
| 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: |
| |
| [source,java] |
| ---- |
| @Partial @Mock DataLoader loader; |
| ---- |
| |
| There are no specific rules for formatting parameter and local variable |
| annotations. |
| |
| [#comments] |
| ==== Comments |
| |
| [#block-comment-style] |
| ===== Block comment style |
| |
| Block comments are indented at the same level as the surrounding code. |
| They may be in `/* ... */` style or `// ...` style. For multi-line |
| `/* ... */` comments, subsequent lines must start with `*` aligned with |
| the `*` on the previous line. |
| |
| [source,java] |
| ---- |
| /* |
| * This is // And so /* Or you can |
| * okay. // is this. * even do this. */ |
| */ |
| ---- |
| |
| Comments are not enclosed in boxes drawn with asterisks or other |
| characters. |
| |
| TIP: When writing multi-line comments, use the `/* ... */` style if |
| you want automatic code formatters to re-wrap the lines when necessary |
| (paragraph-style). Most formatters don't re-wrap lines in `// ...` style |
| comment blocks. |
| |
| [#modifiers] |
| ==== Modifiers |
| |
| Class and member modifiers, when present, appear in the order |
| recommended by the Java Language Specification: |
| |
| [source,java] |
| ---- |
| public protected private abstract static final transient volatile synchronized native strictfp |
| ---- |
| |
| [#numeric-literals] |
| ==== Numeric Literals |
| |
| `long`-valued integer literals use an uppercase `L` suffix, never |
| lowercase (to avoid confusion with the digit `1`). For example, |
| `3000000000L` rather than `3000000000l`. |
| |
| [#naming] |
| == Naming |
| |
| [#identifier-names] |
| === Rules common to all identifiers |
| |
| Identifiers use only ASCII letters and digits, and in two cases noted |
| below, underscores. Thus each valid identifier name is matched by the |
| regular expression `\w+` . |
| |
| In Google Style special prefixes or suffixes, like those seen in the |
| examples `name_`, `mName`, `s_name` and `kName`, are *not* used. |
| |
| [#specific-identifier-names] |
| === Rules by identifier type |
| |
| [#package-names] |
| ==== Package names |
| |
| Package names are all lowercase, with consecutive words simply |
| concatenated together (no underscores). For example, |
| `com.example.deepspace`, not `com.example.deepSpace` or |
| `com.example.deep_space`. |
| |
| [#class-names] |
| ==== Class names |
| |
| Class names are written in link:#camel-case[UpperCamelCase]. |
| |
| Class names are typically nouns or noun phrases. For example, |
| `Character` or `ImmutableList`. Interface names may also be nouns or |
| noun phrases (for example, `List`), but may sometimes be adjectives or |
| adjective phrases instead (for example, `Readable`). |
| |
| 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`. |
| |
| [#method-names] |
| ==== Method names |
| |
| Method names are written in link:#s5.3-camel-case[lowerCamelCase]. |
| |
| Method names are typically verbs or verb phrases. For example, |
| `sendMessage` or `stop`. |
| |
| Underscores may appear in JUnit _test_ method names to separate logical |
| components of the name. One typical pattern is |
| `test<MethodUnderTest>_<state>`, for example `testPop_emptyStack`. There |
| is no One Correct Way to name test methods. |
| |
| [#constant-names] |
| ==== Constant names |
| |
| [[constants]] |
| Constant names use `CONSTANT_CASE`: all uppercase letters, with words |
| separated by underscores. But what _is_ a constant, exactly? |
| |
| Every constant is a static final field, but not all static final fields |
| are constants. Before choosing constant case, consider whether the field |
| really _feels like_ a constant. For example, if any of that instance's |
| observable state can change, it is almost certainly not a constant. |
| Merely _intending_ to never mutate the object is generally not enough. |
| Examples: |
| |
| [source,java] |
| ---- |
| // Constants |
| static final int NUMBER = 5; |
| static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann"); |
| 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"; |
| final String nonStatic = "non-static"; |
| static final Set<String> mutableCollection = new HashSet<String>(); |
| static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable); |
| static final Logger logger = Logger.getLogger(MyClass.getName()); |
| static final String[] nonEmptyArray = {"these", "can", "change"}; |
| ---- |
| |
| These names are typically nouns or noun phrases. |
| |
| [#non-constant-field-names] |
| ==== Non-constant field names |
| |
| Non-constant field names (static or otherwise) are written in |
| link:#camel-case[lowerCamelCase]. |
| |
| These names are typically nouns or noun phrases. For example, |
| `computedValues` or `index`. |
| |
| [#parameter-names] |
| ==== Parameter names |
| |
| Parameter names are written in link:#camel-case[lowerCamelCase]. |
| |
| One-character parameter names should be avoided. |
| |
| [#local-variable-names] |
| ==== Local variable names |
| |
| Local variable names are written in link:#camel-case[lowerCamelCase], |
| and can be abbreviated more liberally than other types of names. |
| |
| However, one-character names should be avoided, except for temporary and |
| looping variables. |
| |
| Even when final and immutable, local variables are not considered to be |
| constants, and should not be styled as constants. |
| |
| [#type-variable-names] |
| ==== Type variable names |
| |
| Each type variable is named in one of two styles: |
| |
| * A single capital letter, optionally followed by a single numeral (such |
| as `E`, `T`, `X`, `T2`) |
| * A name in the form used for classes (see link:#class-names[Class |
| names]), followed by the capital letter `T` (examples: `RequestT`, |
| `FooBarT`). |
| |
| [#camel-case] |
| === Camel case: defined |
| |
| [[acronyms]] |
| [[camelcase]] |
| Sometimes there is more than one reasonable way to convert an English |
| phrase into camel case, such as when acronyms or unusual constructs like |
| "IPv6" or "iOS" are present. To improve predictability, Google Style |
| specifies the following (nearly) deterministic scheme. |
| |
| Beginning with the prose form of the name: |
| |
| 1. Convert the phrase to plain ASCII and remove any apostrophes. For |
| example, "Müller's algorithm" might become "Muellers algorithm". |
| 2. Divide this result into words, splitting on spaces and any remaining |
| punctuation (typically hyphens). |
| * _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 that a word such as "iOS" is not |
| really in camel case _per se_; it defies _any_ convention, so this |
| recommendation does not apply. |
| 3. Now lowercase _everything_ (including acronyms), then uppercase only |
| the first character of: |
| * ... each word, to yield _upper camel case_, or |
| * ... each word except the first, to yield _lower camel case_ |
| 4. Finally, join all the words into a single identifier. |
| |
| Note that the casing of the original words is almost entirely |
| disregarded. Examples: |
| |
| [cols=",,",options="header",] |
| |================================================================= |
| |Prose form |Correct |Incorrect |
| |"XML HTTP request" |`XmlHttpRequest` |`XMLHTTPRequest` |
| |"new customer ID" |`newCustomerId` |`newCustomerID` |
| |"inner stopwatch" |`innerStopwatch` |`innerStopWatch` |
| |"supports IPv6 on iOS?" |`supportsIpv6OnIos` |`supportsIPv6OnIOS` |
| |"YouTube importer" |`YouTubeImporter` + |
| `YoutubeImporter`* | |
| |================================================================= |
| |
| *Acceptable, but not recommended. |
| |
| NOTE: Some words are ambiguously hyphenated in the English language: |
| for example "nonempty" and "non-empty" are both correct, so the method |
| names `checkNonempty` and `checkNonEmpty` are likewise both correct. |
| |
| [#programming-practices] |
| == Programming Practices |
| |
| [#override-annotation] |
| === @Override: always used |
| |
| A method is marked with the `@Override` annotation whenever it is legal. |
| This includes a class method overriding a superclass method, a class |
| method implementing an interface method, and an interface method |
| respecifying a superinterface method. |
| |
| **Exception:** `@Override` may be omitted when the parent method is |
| `@Deprecated`. |
| |
| [#caught-exceptions] |
| === Caught exceptions: not ignored |
| |
| [[caughtexceptions]] |
| Except as noted below, it is very rarely correct to do nothing in |
| response to a caught exception. (Typical responses are to log it, or if |
| it is considered "impossible", rethrow it as an `AssertionError`.) |
| |
| When it truly is appropriate to take no action whatsoever in a catch |
| block, the reason this is justified is explained in a comment. |
| |
| [source,java] |
| ---- |
| try { |
| int i = Integer.parseInt(response); |
| return handleNumericResponse(i); |
| } catch (NumberFormatException ok) { |
| // it's not numeric; that's fine, just continue |
| } |
| return handleTextResponse(response); |
| ---- |
| |
| *Exception:* In tests, a caught exception may be ignored without comment |
| _if_ it is named `expected`. The following is a very common idiom for |
| ensuring that the method under test _does_ throw an exception of the |
| expected type, so a comment is unnecessary here. |
| |
| [source,java] |
| ---- |
| try { |
| emptyStack.pop(); |
| fail(); |
| } catch (NoSuchElementException expected) { |
| } |
| ---- |
| |
| [#static-members] |
| === Static members: qualified using class |
| |
| When a reference to a static class member must be qualified, it is |
| qualified with that class's name, not with a reference or expression of |
| that class's type. |
| |
| [source,java] |
| ---- |
| Foo aFoo = ...; |
| Foo.aStaticMethod(); // good |
| aFoo.aStaticMethod(); // bad |
| somethingThatYieldsAFoo().aStaticMethod(); // very bad |
| ---- |
| |
| [#finalizers] |
| === Finalizers: not used |
| |
| It is *extremely rare* to override `Object.finalize`. |
| |
| TIP: Don't do it. If you absolutely must, first read and understand |
| http://books.google.com/books?isbn=8131726592[_Effective Java_] Item 7, |
| "Avoid Finalizers," very carefully, and _then_ don't do it. |
| |
| [#javadoc] |
| == Javadoc |
| |
| [#javadoc-formatting] |
| === Formatting |
| |
| [#javadoc-multi-line] |
| ==== General form |
| |
| The _basic_ formatting of Javadoc blocks is as seen in this example: |
| |
| [source,java] |
| ---- |
| /** |
| * Multiple lines of Javadoc text are written here, |
| * wrapped normally... |
| */ |
| public int method(String p1) { ... } |
| ---- |
| |
| ... or in this single-line example: |
| |
| [source,java] |
| ---- |
| /** An especially short bit of Javadoc. */ |
| ---- |
| |
| The basic form is always acceptable. The single-line form may be |
| substituted when there are no at-clauses present, and the entirety of |
| the Javadoc block (including comment markers) can fit on a single line. |
| |
| [#javadoc-paragraphs] |
| ==== Paragraphs |
| |
| One blank line—that is, a line containing only the aligned leading |
| asterisk (`*`)—appears between paragraphs, and before the group of |
| "at-clauses" if present. Each paragraph but the first has `<p>` |
| immediately before the first word, with no space after. |
| |
| [#javadoc-at-clauses] |
| ==== At-clauses |
| |
| Any of the standard "at-clauses" that are used appear in the order |
| `@param`, `@return`, `@throws`, `@deprecated`, and these four types |
| never appear with an empty description. When an at-clause doesn't fit on |
| a single line, continuation lines are indented four (or more) spaces |
| from the position of the `@`. |
| |
| [#summary-fragment] |
| === The summary fragment |
| |
| The Javadoc for each class and member begins with a brief *summary |
| fragment*. This 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 *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 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. */`. |
| |
| [#javadoc-where-required] |
| === Where Javadoc is used |
| |
| [[javadoc-optional]] |
| At the _minimum_, Javadoc is present for every `public` class, and every |
| `public` or `protected` member of such a class, with a few exceptions |
| noted below. |
| |
| Other classes and members still have Javadoc _as needed_. Whenever an |
| implementation comment would be used to define the overall purpose or |
| behavior of a class, method or field, that comment is written as Javadoc |
| instead. (It's more uniform, and more tool-friendly.) |
| |
| [#javadoc-exception-self-explanatory] |
| ==== Exception: self-explanatory methods |
| |
| 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". |
| |
| 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 named `getCanonicalName`, don't omit its |
| documentation (with the rationale that it would say only |
| `/** Returns the canonical name. */`) if a typical reader may have no |
| idea what the term "canonical name" means! |
| |
| [#javadoc-exception-overrides] |
| ==== Exception: overrides |
| |
| Javadoc is not always present on a method that overrides a supertype |
| method. |