tiennm99/styleguide
1
0 Fork 0
mirror of https://github.com/tiennm99/styleguide.git synced 2026-10-12 16:15:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

java: update to latest

Browse Source 
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 <span> tag
* Change `<a name` anchors to `<a id` anchors
* Improve inclusive language usage
* Reword title sentence about documenting a warning to better reflect the advice that follows it
* Fix an unclosed <a> tag around sort_java_imports
* Clarify guidance on java vs javatests

PiperOrigin-RevId: 648433358
This commit is contained in:
Mike Frysinger committed 2024-07-01 15:07:32 -04:00
1 parent 729557a4a2
commit cbc2e01826
1 file changed
+68 -64
Download Patch File Download Diff File Expand all files Collapse all files
javaguide.html
+68 -64
View File
@@ -1,26 +1,28 @@
<!DOCTYPE html>
<html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<title>Google Java Style Guide</title>
<link rel="stylesheet" type="text/css" href="javaguide.css">
<script language="javascript" src="include/styleguide.js"></script>
<link rel="shortcut icon" type="image/x-icon" href="https://www.google.com/favicon.ico" />
<link rel="stylesheet" href="javaguide.css">
<script src="include/styleguide.js"></script>
<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>
</head>
<body onload="initStyleGuide();">
<div id="content">
<h1>Google Java Style Guide</h1>
<div class="vertical_toc" id="tocDiv"></div>
<div id="tocDiv" class="vertical_toc"></div>
<div class="main_body">
<h2 id="s1-introduction">1 Introduction</h2>
<p>This document serves as the <strong>complete</strong> definition of Google's coding standards for
source code in the Java&#8482; Programming Language. A Java source file is described as being <em>in
source code in the Java™ Programming Language. A Java source file is described as being <em>in
Google Style</em> if and only if it adheres to the rules herein.</p>
<p>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 <strong>hard-and-fast rules</strong> that we follow universally, and
@@ -29,6 +31,8 @@ avoids giving <em>advice</em> that isn't clearly enforceable (whether by human o
<h3 id="s1.1-terminology">1.1 Terminology notes</h3>
<p>In this document, unless otherwise clarified:</p>
@@ -94,14 +98,14 @@ anywhere in a source file. This implies that:</p>
<code class="prettyprint lang-java">\'</code> and
<code class="prettyprint lang-java">\\</code>), that sequence
is used rather than the corresponding octal
(e.g.&#160;<code class="badcode">\012</code>) or Unicode
(e.g.&#160;<code class="badcode">\u000a</code>) escape.</p>
(e.g. <code class="badcode">\012</code>) or Unicode
(e.g. <code class="badcode">\u000a</code>) escape.</p>
<h4 id="s2.3.3-non-ascii-characters">2.3.3 Non-ASCII characters</h4>
<p>For the remaining non-ASCII characters, either the actual Unicode character
(e.g.&#160;<code class="prettyprint lang-java">&#8734;</code>) or the equivalent Unicode escape
(e.g.&#160;<code class="prettyprint lang-java">\u221e</code>) is used. The choice depends only on
(e.g. <code class="prettyprint lang-java">∞</code>) or the equivalent Unicode escape
(e.g. <code class="prettyprint lang-java">\u221e</code>) is used. The choice depends only on
which makes the code <strong>easier to read and understand</strong>, although Unicode escapes
outside string literals and comments are strongly discouraged.</p>
@@ -117,12 +121,12 @@ Unicode characters are used, an explanatory comment can be very helpful.</p>
</tr>
<tr>
<td><code class="prettyprint lang-java">String unitAbbrev = "&#956;s";</code></td>
<td><code class="prettyprint lang-java">String unitAbbrev = "μs";</code></td>
<td>Best: perfectly clear even without a comment.</td>
</tr>
<tr>
<td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; // "&#956;s"</code></td>
<td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; // "μs"</code></td>
<td>Allowed, but there's no reason to do this.</td>
</tr>
@@ -149,7 +153,7 @@ some programs might not handle non-ASCII characters properly. If that should hap
programs are <strong>broken</strong> and they must be <strong>fixed</strong>.</p>
<a name="filestructure"></a>
<a id="filestructure"></a>
<h2 id="s3-source-file-structure">3 Source file structure</h2>
<div>
@@ -176,7 +180,7 @@ programs are <strong>broken</strong> and they must be <strong>fixed</strong>.</p
<p>The package statement is <strong>not line-wrapped</strong>. The column limit (Section 4.4,
<a href="#s4.4-column-limit">Column limit: 100</a>) does not apply to package statements.</p>
<a name="imports"></a>
<a id="imports"></a>
<h3 id="s3.3-import-statements">3.3 Import statements</h3>
<h4 id="s3.3.1-wildcard-imports">3.3.1 No wildcard imports</h4>
@@ -214,12 +218,12 @@ normal imports.</p>
<h3 id="s3.4-class-declaration">3.4 Class declaration</h3>
<a name="oneclassperfile"></a>
<a id="oneclassperfile"></a>
<h4 id="s3.4.1-one-top-level-class">3.4.1 Exactly one top-level class declaration</h4>
<p>Each top-level class resides in a source file of its own.</p>
<a name="s3.4.2-class-member-ordering"></a>
<a id="s3.4.2-class-member-ordering"></a>
<h4 id="s3.4.2-ordering-class-contents">3.4.2 Ordering of class contents</h4>
<p>The order you choose for the members and initializers of your class can have a great effect on
@@ -233,7 +237,7 @@ ordering.</p>
<a name="overloads"></a>
<a id="overloads"></a>
<h5 id="s3.4.2.1-overloads-never-split">3.4.2.1 Overloads: never split</h5>
<p>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
<a href="#s4.8.3.1-array-initializers">array initializers</a>, any array initializer
<em>may</em> optionally be treated as if it were a block-like construct.</p>
<a name="braces"></a>
<a id="braces"></a>
<h3 id="s4.1-braces">4.1 Braces</h3>
<h4 id="s4.1.1-braces-always-used">4.1.1 Use of optional braces</h4>
@@ -266,7 +270,7 @@ body is empty or contains only a single statement.</p>
<h4 id="s4.1.2-blocks-k-r-style">4.1.2 Nonempty blocks: K &amp; R style</h4>
<p>Braces follow the Kernighan and Ritchie style
("<a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a>")
("<a href="https://blog.codinghorror.com/new-programming-jargon/#3">Egyptian brackets</a>")
for <em>nonempty</em> blocks and block-like constructs:</p>
<ul>
@@ -319,7 +323,7 @@ return new MyClass() {
<p>A few exceptions for enum classes are given in Section 4.8.1,
<a href="#s4.8.1-enum-classes">Enum classes</a>.</p>
<a name="emptyblocks"></a>
<a id="emptyblocks"></a>
<h4 id="s4.1.3-braces-empty-blocks">4.1.3 Empty blocks: may be concise</h4>
<p>An empty block or block-like construct may be in K &amp; R style (as described in
@@ -356,7 +360,7 @@ applies to both code and comments throughout the block. (See the example in Sect
<p>Each statement is followed by a line break.</p>
<a name="columnlimit"></a>
<a id="columnlimit"></a>
<h3 id="s4.4-column-limit">4.4 Column limit: 100</h3>
<p>Java code has a column limit of 100 characters. A "character" means any Unicode code point.
@@ -461,7 +465,7 @@ Predicate&lt;String&gt; predicate = str -&gt;
<p class="note"><strong>Note:</strong> The primary goal for line wrapping is to have clear
code, <em>not necessarily</em> code that fits in the smallest number of lines.</p>
<a name="indentation"></a>
<a id="indentation"></a>
<h4 id="s4.5.2-line-wrapping-indent">4.5.2 Indent continuation lines at least +4 spaces</h4>
<p>When line-wrapping, each line after the first (each <em>continuation line</em>) is indented
@@ -602,15 +606,15 @@ private int x; // permitted, but future edits
private Color color; // may leave it unaligned
</pre>
<p class="tip"><strong>Tip:</strong> 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 <strong>allowed</strong>. 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.</p>
<p class="tip"><strong>Tip:</strong> 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.</p>
<a name="parentheses"></a>
<a id="parentheses"></a>
<h3 id="s4.7-grouping-parentheses">4.7 Grouping parentheses: recommended</h3>
<p>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
<p>Since enum classes <em>are classes</em>, all other rules for formatting classes apply.</p>
<a name="localvariables"></a>
<a id="localvariables"></a>
<h4 id="s4.8.2-variable-declarations">4.8.2 Variable declarations</h4>
<h5 id="s4.8.2.1-variables-per-declaration">4.8.2.1 One variable per declaration</h5>
@@ -707,7 +711,7 @@ the <em>last</em> statement group, <em>zero</em> or more statements).</p>
as if a block were being opened. The following switch label returns to the previous indentation
level, as if a block had been closed.</p>
<a name="fallthrough"></a>
<a id="fallthrough"></a>
<h5 id="s4.8.4.2-switch-fall-through">4.8.4.2 Fall-through: commented</h5>
<p>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.
</p>
<a name="annotations"></a>
<a id="annotations"></a>
<h4 id="s4.8.5-annotations">4.8.5 Annotations</h4>
<h5 id="s4.8.5.1-type-use-annotation-style">4.8.5.1 Type-use annotations</h5>
@@ -804,7 +808,7 @@ for example:</p>
<p>There are no specific rules for formatting annotations on parameters or local variables (except,
of course, when the annotation is a type-use annotation).</p>
<a name="comments"></a>
<a id="comments"></a>
<h4 id="s4.8.6-comments">4.8.6 Comments</h4>
<p>This section addresses <em>implementation comments</em>. Javadoc is addressed separately in
@@ -835,9 +839,9 @@ Such a comment renders the line non-blank.</p>
re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in
<code class="prettyprint lang-java">// ...</code> style comment blocks.</p>
<a name="modifiers"></a>
<a id="modifiers"></a>
<h4 id="s4.8.7-modifiers">4.8.7 Modifiers</h4>
<p>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 <code>1</code>). For example, <code>3000000000L</code>
rather than <code class="badcode">3000000000l</code>.</p>
<a name="naming"></a>
<a id="naming"></a>
<h2 id="s5-naming">5 Naming</h2>
<h3 id="s5.1-identifier-names">5.1 Rules common to all identifiers</h3>
@@ -866,6 +870,8 @@ underscores. Thus each valid identifier name is matched by the regular expressio
names are not Google Style: <code class="badcode">name_</code>, <code class="badcode">mName</code>,
<code class="badcode">s_name</code> and <code class="badcode">kName</code>.</p>
<h3 id="s5.2-specific-identifier-names">5.2 Rules by identifier type</h3>
<h4 id="s5.2.1-package-names">5.2.1 Package names</h4>
@@ -907,7 +913,7 @@ name, with <em>each</em> component written in <a href="#s5.3-camel-case">lowerCa
example <code class="prettyprint lang-java">transferMoney_deductsFromSource</code>. There is no One
Correct Way to name test methods.</p>
<a name="constants"></a>
<a id="constants"></a>
<h4 id="s5.2.4-constant-names">5.2.4 Constant names</h4>
<p>Constant names use <code class="prettyprint lang-java">UPPER_SNAKE_CASE</code>: all uppercase
@@ -978,8 +984,8 @@ be styled as constants.</p>
<code class="prettyprint lang-java">FooBarT</code>).</li>
</ul>
<a name="acronyms"></a>
<a name="camelcase"></a>
<a id="acronyms"></a>
<a id="camelcase"></a>
<h3 id="s5.3-camel-case">5.3 Camel case: defined</h3>
<p>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
<p>Beginning with the prose form of the name:</p>
<ol>
<li>Convert the phrase to plain ASCII and remove any apostrophes. For example, "M&#252;ller's
<li>Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's
algorithm" might become "Muellers algorithm".</li>
<li>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
<ul>
<li><em>Recommended:</em> if any word already has a conventional camel-case appearance in common
usage, split this into its constituent parts (e.g., "AdWords" becomes "ad&#160;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 <em>per se</em>; it defies <em>any</em>
convention, so this recommendation does not apply.</li>
</ul>
@@ -1048,6 +1054,11 @@ predictability, Google Style specifies the following (nearly) deterministic sche
<code class="prettyprint lang-java">YoutubeImporter</code>*</td>
<td></td>
</tr>
<tr>
<td>"Turn on 2SV"</td>
<td><code class="prettyprint lang-java">turnOn2sv</code></td>
<td><code class="badcode">turnOn2Sv</code></td>
</tr>
</tbody></table>
<p>*Acceptable, but not recommended.</p>
@@ -1071,7 +1082,7 @@ method.</p>
<code class="prettyprint lang-java">@Override</code> may be omitted when the parent method is
<code class="prettyprint lang-java">@Deprecated</code>.</p>
<a name="caughtexceptions"></a>
<a id="caughtexceptions"></a>
<h3 id="s6.2-caught-exceptions">6.2 Caught exceptions: not ignored</h3>
<p>Except as noted below, it is very rarely correct to do nothing in response to a caught
@@ -1113,21 +1124,14 @@ Foo.aStaticMethod(); // good
<span class="badcode">somethingThatYieldsAFoo().aStaticMethod();</span> // very bad
</pre>
<a name="finalizers"></a>
<a id="finalizers"></a>
<h3 id="s6.4-finalizers">6.4 Finalizers: not used</h3>
<p>It is <strong>extremely rare</strong> to override <code class="prettyprint
lang-java">Object.finalize</code>.</p>
<p class="tip"><strong>Tip:</strong> Don't do it. If you absolutely must, first read and understand
<p>Do not override <code class="prettyprint lang-java">Object.finalize</code>. Finalization support
is <a href="https://openjdk.org/jeps/421"><em>scheduled for removal</em></a>.</p>
<a href="http://books.google.com/books?isbn=0134686047"><em>Effective Java</em> Item 8</a>,
"Avoid finalizers and cleaners" very carefully, and <em>then</em> don't do it.</p>
<a name="javadoc"></a>
<a id="javadoc"></a>
<h2 id="s7-javadoc">7 Javadoc</h2>
@@ -1152,9 +1156,9 @@ public int method(String p1) { ... }
<p>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 <code>@return</code>.
applies when there are no block tags such as <code>@return</code>.</p>
</p><h4 id="s7.1.2-javadoc-paragraphs">7.1.2 Paragraphs</h4>
<h4 id="s7.1.2-javadoc-paragraphs">7.1.2 Paragraphs</h4>
<p>One blank line—that is, a line containing only the aligned leading asterisk
(<code>*</code>)—appears between paragraphs, and before the group of block tags if present.
@@ -1162,9 +1166,9 @@ Each paragraph except the first has <code>&lt;p&gt;</code> immediately before th
no space after it. HTML tags for other block-level elements, such as <code>&lt;ul&gt;</code> or
<code>&lt;table&gt;</code>, are <em>not</em> preceded with <code>&lt;p&gt;</code>.</p>
<a name="s7.1.3-javadoc-at-clauses"></a>
<a id="s7.1.3-javadoc-at-clauses"></a>
</p><h4 id="s7.1.3-javadoc-block-tags">7.1.3 Block tags</h4>
<h4 id="s7.1.3-javadoc-block-tags">7.1.3 Block tags</h4>
<p>Any of the standard "block tags" that are used appear in the order <code>@param</code>,
<code>@return</code>, <code>@throws</code>, <code>@deprecated</code>, and these four types never
@@ -1178,7 +1182,7 @@ are indented four (or more) spaces from the position of the <code>@</code>.
fragment is very important: it is the only part of the text that appears in certain contexts such as
class and method indexes.</p>
<p>This is a fragment&#8212;a noun phrase or verb phrase, not a complete sentence. It does
<p>This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does
<strong>not</strong> begin with <code class="badcode">A {@code Foo} is a...</code>, or
<code class="badcode">This method returns...</code>, nor does it form a complete imperative sentence
like <code class="badcode">Save the record.</code>. However, the fragment is capitalized and
@@ -1189,7 +1193,7 @@ punctuated as if it were a complete sentence.</p>
incorrect, and should be changed to
<code class="prettyprint lang-java">/** Returns the customer ID. */</code>.</p>
<a name="s7.3.3-javadoc-optional"></a>
<a id="s7.3.3-javadoc-optional"></a>
<h3 id="s7.3-javadoc-where-required">7.3 Where Javadoc is used</h3>
<p>At the <em>minimum</em>, Javadoc is present for every
@@ -1232,9 +1236,9 @@ class or member, that comment is written as Javadoc instead (using <code>/**</co
<p>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.</p>
</div>
</div>
</div>
</body>
</html>
</html>