This document is a complete definition of the Google Java Programming style specification. When and only if a Java source file conforms to the rules in this document, we think it conforms to Google's Java programming style.
As with other programming style guides, this is not just about the beauty of the coding format, but also about conventions and coding standards. However, this document focuses primarily on the rules that we generally follow, and we try to avoid providing advice to those who are not explicitly obligated to do so.
In this document, unless otherwise noted:
Other term descriptions will occasionally appear in subsequent documents.
The sample code in this document is not a specification. That said, while the sample code follows Google's programming style, it doesn't mean that this is the only way to show the code. The format selection in the example should not be enforced as a rule.
The source file is named with its topmost class name, is case-sensitive, and has a file name extension.java.
The source file encoding format is UTF-8.
In addition to the line terminator sequence, the ASCII horizontal null characters (0x20, or space) is the only white space character allowed in the source file, which means:
For any character that has a special escape sequence (\b, \ t, \ n, \f, \ r, \ ", \" and \), we use its escape sequence instead of the corresponding octal (for example\012) or Unicode (for example\u000a) escape.
For the remaining non-ASCII characters, the actual Unicode characters (such as ∞) are used, or equivalent Unicode escape characters (such as \u221e) are used, depending on which one makes the code easier to read and understand.
Tip: When using Unicode escape characters or some actual Unicode characters, it is recommended to make some comments to explain, which helps others to read and understand.
For example:
String unitAbbrev = "μs"; | Like, very clear even without comments String unitAbbrev = "\ u03bcs"; // "μs" | allowed, but there is no reason to do this String unitAbbrev = "\ u03bcs"; // Greek letter mu, "s" | allowed, but this is clumsy and error-prone String unitAbbrev = "\ u03bcs"; | sucks, readers do n’t see what it is return ‘\ ufeff’ + content; // byte order mark | Good, for non-printing characters, use escapes and write comments if necessary
source file StructureTIP: Never let your code become less readable because you're afraid some programs might not handle non-ASCII characters correctly. When the program does not correctly handle non-ASCII characters, it does not run correctly, and you will be able to fix these problems. (it means daring to use non-ASCII characters, if necessary.)
A source file contains (in order):
Each of these sections is separated by a blank line.
If a file contains license or copyright information, it should be placed at the front of the file.
The package statement does not wrap, and the column limit (Section 4.4) does not apply to the package statement. (That is, the package statement is written in one line)
That is, do not appear with an import statement like this:import java.util.*;
The import statement does not wrap, and the column limit (Section 4.4) does not apply to the import statement. (separate rows per import statement)
The import statement can be divided into the following groups, each separated by a blank line in this order:
The lines within the group are not empty, sorted by dictionary order.
Each top-level class is in a source file that has the same name as it (and, of course, a.javasuffix).
Exception:package-info.javaThere can be no class in the filepackage-info.
The order of the members of a class has a great impact on usability, but there is no single universal rule. The ordering of members may be different for different classes. Most importantly, each class should sort its members with some logic, and the maintainer should be able to interpret the sort logic. For example, a new method cannot always be habitually added to the end of a class, because it is ordered in chronological order rather than some sort of logic.
When a class has more than one constructor, or multiple methods with the same name, these functions/methods should appear in order, not in the middle of other functions/methods.
Term Description : a block structure (Block-like construct) refers to the body of a class, method, or constructor. It is important to note that the initial values in the array initialization can be optionally treated as a block structure (4.8.3.1 section).
Curly bracesif, else, for, do, whileare used with statements, even if there is only one statement (or null), you should write the curly braces.
For non-empty blocks and block structures, the braces follow the Kernighan and Ritchie styles (Egyptian brackets):
Example:
return new MyClass() { @Override public void method() { if (condition()) { try { something(); } catch (ProblemException e) { recover(); } } } };
The 4.8.1 section gives some exceptions to the enum class.
Nothing is included in an empty block structure, curly braces can be written succinctly{}, and no line breaks are required. Exception: If it is part of a multi-block statement (If/else or try/catch/finally), the closing brace is wrapped even if there is no content inside the curly braces.
Example:
void DoNothing () {}
4.2 Block indent: 2 spaces
Each time a new block is started, the indentation increases by 2 spaces, and when the block ends, the indentation returns the previous indentation level. The indentation level applies to code and comments. (See code example in Section 4.1.2)
Lines are wrapped after each statement.
An item can choose a 80-character or 100-character column limit, with the exception of the following, if any row exceeds the limit of the number of characters, it must be wrapped automatically.
Exception:
Terminology Description : In general, a line of code is divided into multiple lines to avoid exceeding the column limit (80 or 100 characters), which we call word wrap (line-wrapping).
We do not have comprehensive, deterministic criteria for deciding how to wrap in each case. Many times, there are several ways to wrap the same piece of code effectively.
4.5.1 from where to disconnectTip: The extraction method or local variable can solve the problem of long code without wrapping (it is reasonable to shorten the name length bar)
The basic guidelines for wrapping are: more inclined to break at a higher syntax level.
When auto-wrap, each line after the first line is indented at least 4 spaces more than the first line (note: tabs are not used for indentation.) See section 2.3.1).
When there is continuous auto-wrapping, the indentation may be indented more than 4 spaces (when there are multiple levels of syntax elements). In general, two consecutive rows use the same indentation when and only if they start at the sibling syntax element.
The 4.6.3 Horizontal Alignment section indicates that the use of a variable number of empty glyd to align the preceding line's symbols is discouraged.
You need to use a blank line in the following situations:
Multiple consecutive empty lines are allowed, but it is not necessary to do so (we do not encourage this).
In addition to language requirements and other rules, and in addition to text, annotations, and Javadoc use a single space, a single ASCII space also appears in the following places:
4.6.3 Horizontal alignment: no requirementNote: This rule does not require or prohibit one line of the switch or the end requires additional space, only the internal space requirements.
term description : horizontal alignment refers to aligning the character of a line with the corresponding character of the previous line by adding a variable number of spaces.
This is allowed (and there are many places where you can see the code), but Google's programming style does not require it. Even for code that already uses horizontal alignment, we don't need to maintain that style.
The following example shows an unaligned code, followed by an aligned code:
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
4.7 using parentheses to qualify groups: recommended
TIP: Snapping increases code readability, but it can cause problems with future maintenance. Consider a future time when we need to modify a row in a bunch of aligned code. This could result in a very beautiful alignment code becoming misplaced. It is likely that it will prompt you to adjust the padding of the surrounding code so that the heap of code is re-horizontally aligned (for example, the programmer wants to maintain this level of alignment), which will allow you to do a lot of work without effort, increase reviewer and possibly lead to more merge conflicts.
Unless the author and reviewer both think that removing the parentheses will not cause the code to be misunderstood, or that the parentheses will make the code easier to read, we should not remove the parentheses. There is no reason to assume that the reader remembers the entire Java operator precedence table.
Enumeration constants are separated by commas, and line breaks are optional.
An enumeration class without methods and documents can be written in the form of an array initialization:
Private enum Suit {CLUBS, HEARTS, Spades, DIAMONDS}
Because the enumeration class is also a class, all formatting rules that apply to other classes also apply to the enumeration class.
Do not use combination declarations, for exampleint a, b;.
Do not declare a local variable at the beginning of a block of code (this is the practice of the C language), but only when it is needed for the first time. Local variables are best initialized when declared, or initialized as soon as they are declared.
Array initialization can be written as a block structure, for example, the following notation is OK:
4.8.3.2 non-C-style array declarationsnew int[] { 0, 1, 2, 3 } new int[] { 0, 1, 2, 3 } new int[] { 0, 1, 2, 3 } new int[] {0, 1, 2, 3}
The brackets are part of the type:String[] argsrather thanString args[].
Term description : A switch block is enclosed in curly braces for one or more statement groups. Each statement group contains one or more switch labels (case FOO:ordefault:) followed by one or more statements.
Consistent with other block structures, the contents of the switch block are indented into 2 spaces.
Start a new line after each switch label, then indent 2 spaces and write down one or more statements.
Within a switch block, each statement group terminates either bybreak, continue, returnor throwing an exception, or by a comment stating that the program will continue to execute to the next set of statements, and any comment that can express that meaning is OK (typically used// fall through). This special note does not need to appear in the last statement group (typicallydefault). Example:
4.8.4.3 the default situation is to be written.switch (input) { case 1: case 2: prepareOneOrTwo(); // fall through case 3: handleOneTwoOrThree(); break; default: handleLargeNumber(input); }
Each switch statement contains adefaultstatement group, even if it does not contain any code.
Annotations are immediately following the document block, applied to classes, methods, and constructors, and a single note is exclusive to one line. These line breaks do not belong to wrap (section 4.5, wrap), so the indentation level does not change. For example:
@Override @Nullable public String getNameIfPresent() { ... }
exception : A single annotation can appear on the same line as the first line of the signature. For example:
@Override public int hashcode () {...}
Annotations applied to a field appear immediately after the document block, and multiple annotations applied to the field allow the field to appear on the same line. For example:
@Partial @Mock Dataloader Loader;
There are no specific rules for parameter and local variable annotations.
The block comment is at the same indentation level as the code surrounding it. They can be either/* ... */style or// ...style. For multiple lines of/* ... */comments, subsequent lines must*start and align with the previous line*. The following sample comments are OK.
/* * This is // And so /* Or you can * okay. // is this. * even do this. */ */
Note Do not enclose in frames drawn by asterisks or other characters.
4.8.7 ModifiersTip: When writing multiline comments, use if you want to be able to re-line if necessary (that is, the comment is like a paragraph style)/* ... */.
The modifiers of classes and members appear in the order recommended by the Java language Specification, if they exist.
Naming convention 5.1 rules that are common to all identifiersPublic protected private abstract static final transient volatile synchronized native STRICTFP
Identifiers can only use ASCII letters and numbers, so each valid identifier name can match a regular expression\w+.
Special prefixes or suffixes used in other Google programming language styles, such as,name_, mName s_nameandkName, are no longer used in the Java programming style.
The package name is all lowercase, and successive words are simply concatenated, without underlining.
Class names areUpperCamelCasewritten in style.
The class name is usually a noun or noun phrase, and the interface name can sometimes be an adjective or an adjective phrase. There are no specific rules or valid conventions for naming annotation types.
The test class is named to end with the name of the class it wants to testTest. For example,HashTestorHashIntegrationTest.
Method names arelowerCamelCasewritten in style.
The method name is usually a verb or a verb phrase.
The underscore may appear in the JUnit test method name to separate the logical components of the name. A typical pattern is:test<MethodUnderTest>_<state>, for exampletestPop_emptyStack. There is no single right way to name a test method.
The constant name is named ModeCONSTANT_CASE, with all uppercase letters, and the words separated by underscores. So, what exactly is a constant?
Each constant is a static final field, but not all static final fields are constants. When deciding whether a field is a constant, consider whether it really feels like a constant. For example, if any one of the observed states of the instance is mutable, it will almost certainly not be a constant. Just never打算change the object generally is not enough, it must be really unchanged in order to show it as a constant.
// 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 usually nouns or noun phrases.
The number of field names islowerCamelCasewritten in style.
These names are usually nouns or noun phrases.
The name of the parameter islowerCamelCasewritten in style.
Parameters should avoid naming with a single character.
Local variable nameslowerCamelCaseare written in style, and local variable names can have looser abbreviations than other types of names.
Although the abbreviations are looser, you should avoid naming them with single characters, except for temporary and cyclic variables.
Even if the local variable is final and immutable, it should not be shown as a constant, nor can it be named with constant rules.
Type variables can be named in one of the following two styles:
The Hump-type nomenclature is divided into large hump-type nomenclature (UpperCamelCase) and small hump-type nomenclature (lowerCamelCase). Sometimes we have more than one reasonable way to convert an English phrase into a hump form, such as an abbreviation or an unusual structure (such as "IPv6" or "IOS"). Google has specified the following conversion scenarios.
The name散文形式begins with (prose form):
Example:
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*
Asterisking indicates yes, but not recommended.
Programming Practice 6.1 @Override: can be usedNote: in English, some word forms with hyphens are not unique. For example: "NonEmpty" and "non-empty" are all correct, so the method namecheckNonemptyandcheckNonEmptyboth are correct.
As long as it is legal,@Overrideuse the annotations.
In addition to the following example, it is rarely correct to respond to a caught exception. (A typical response is to print the log, or if it is considered impossible, treat it as a re-AssertionErrorthrow.) )
If it does not need to do any response in the catch block, a comment is required (as in the example below).
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 a test, if a caught exception is namedexpected, it can be ignored without comment. The following is a very common scenario to ensure that the method being tested throws an expected exception, so there is no need to annotate it here.
6.3 Static members: calling using the classtry { emptyStack.pop(); fail(); } catch (NoSuchElementException expected) { }
Use the class name to invoke a static class member instead of a specific object or expression.
6.4 Finalizers: DisableFoo aFoo = ...; Foo.aStaticMethod(); // good aFoo.aStaticMethod(); // bad somethingThatYieldsAFoo().aStaticMethod(); // very bad
Rarely to be overloadedObject.finalize.
Javadoc7.1 Format 7.1.1 General formTIP: Do not use finalize. If you want to use it, please read and understand effective Java 7th: "Avoid finalizers", then do not use it.
The basic format of the Javadoc block is as follows:
/** * Multiple lines of Javadoc text are written here, * wrapped normally... */ public int method(String p1) { ... }
Or one of the following single-line forms:
/** a especially short bit of Javadoc. */
The basic format is always OK. A single-line form can be used when the entire Javadoc block can fit into a row (and there is no Javadoc tag @xxx).
Blank lines (that is, rows that contain only the leftmost asterisk) appear between paragraphs and before the Javadoc tag (@XXX), if any. In addition to the first paragraph, each paragraph has a label before the first word<p>, and there are no spaces between it and the first word.
The standard Javadoc tags appear in the following order:,,,@param @return @throws @deprecatedbefore these 4 kinds of tags appear, the description cannot be empty. When the description cannot be accommodated in a row, successive lines need to be indented at least 4 more spaces.
The Javadoc of each class or member begins with a short digest fragment. This fragment is very important, and in some cases it is the only text that appears, such as in the class and method indexes.
This is just a small fragment, can be a noun phrase or a verb phrase, but not a complete sentence. It will notA {@code Foo} is a...start with orThis method returns...begin, and it will not be a complete imperative, as inSave the record.... However, it looks like a complete sentence because it is capitalized and punctuation is added.
7.3 Where to use JavadocTIP: A common mistake is to write a simple Javadoc/** @return the customer ID */, which is not true. It should be written/** Returns the customer ID. */.
Use Javadoc at least for each public class and every public and protected member of it, here are some exceptions:
For simple and obvious methods such asgetFoo, Javadoc is optional (i.e., can not be written). In this case, in addition to writing "Returns the Foo", there is really nothing worth writing about.
The test methods in the unit test class are probably the most common examples of self-evident, and we can usually tell from the descriptive naming of these methods what it does, so no additional documentation is required.
7.3.2 Exceptions: OverloadingTIP: If there is some information that needs to be understood by the reader, the above exceptions should not be a justification for ignoring this information. For example, thegetCanonicalNamedocument description should not be overlooked for the method name because the reader may not knowcanonical namewhat the word refers to.
If a method overloads a method in a superclass, then Javadoc is not required.
For classes and methods that are not visible outside the package, you also want to use Javadoc if necessary. If a comment is used to define the overall purpose or behavior of a class, method, field, then this annotation should be written as Javadoc, which is more uniform and friendlier.
This document is translated from Google Java Style, author @hawstein.
Google Java Programming style guide Chinese version (GO)
Start building with 50+ products and up to 12 months usage for Elastic Compute Service
1 on 1 presale consultation
24/7 Technical Support 6 Free Tickets per Quarter Faster Response
Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.
A comprehensive suite of global cloud computing services to power your business
Payment Methods We Support
