1*8c35d5eeSXin Li<!DOCTYPE html> 2*8c35d5eeSXin Li<html> 3*8c35d5eeSXin Li<head> 4*8c35d5eeSXin Li<meta http-equiv="content-type" content="text/html; charset=UTF-8"> 5*8c35d5eeSXin Li<title>Google Java Style Guide</title> 6*8c35d5eeSXin Li<link rel="stylesheet" type="text/css" href="javaguide.css"> 7*8c35d5eeSXin Li<script language="javascript" src="include/styleguide.js"></script> 8*8c35d5eeSXin Li<link rel="shortcut icon" type="image/x-icon" href="https://www.google.com/favicon.ico" /> 9*8c35d5eeSXin Li<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script> 10*8c35d5eeSXin Li</head> 11*8c35d5eeSXin Li<body onload="initStyleGuide();"> 12*8c35d5eeSXin Li<div id="content"> 13*8c35d5eeSXin Li<h1>Google Java Style Guide</h1> 14*8c35d5eeSXin Li<div class="vertical_toc" id="tocDiv"></div> 15*8c35d5eeSXin Li 16*8c35d5eeSXin Li<div class="main_body"> 17*8c35d5eeSXin Li 18*8c35d5eeSXin Li<h2 id="s1-introduction">1 Introduction</h2> 19*8c35d5eeSXin Li 20*8c35d5eeSXin Li<p>This document serves as the <strong>complete</strong> definition of Google's coding standards for 21*8c35d5eeSXin Lisource code in the Java™ Programming Language. A Java source file is described as being <em>in 22*8c35d5eeSXin LiGoogle Style</em> if and only if it adheres to the rules herein.</p> 23*8c35d5eeSXin Li 24*8c35d5eeSXin Li<p>Like other programming style guides, the issues covered span not only aesthetic issues of 25*8c35d5eeSXin Liformatting, but other types of conventions or coding standards as well. However, this document 26*8c35d5eeSXin Lifocuses primarily on the <strong>hard-and-fast rules</strong> that we follow universally, and 27*8c35d5eeSXin Liavoids giving <em>advice</em> that isn't clearly enforceable (whether by human or tool). 28*8c35d5eeSXin Li</p> 29*8c35d5eeSXin Li 30*8c35d5eeSXin Li 31*8c35d5eeSXin Li 32*8c35d5eeSXin Li<h3 id="s1.1-terminology">1.1 Terminology notes</h3> 33*8c35d5eeSXin Li 34*8c35d5eeSXin Li<p>In this document, unless otherwise clarified:</p> 35*8c35d5eeSXin Li 36*8c35d5eeSXin Li<ol> 37*8c35d5eeSXin Li <li>The term <em>class</em> is used inclusively to mean an "ordinary" class, enum class, 38*8c35d5eeSXin Li interface or annotation type (<code class="prettyprint lang-java">@interface</code>).</li> 39*8c35d5eeSXin Li 40*8c35d5eeSXin Li <li>The term <em>member</em> (of a class) is used inclusively to mean a nested class, field, 41*8c35d5eeSXin Li method, <em>or constructor</em>; that is, all top-level contents of a class except initializers 42*8c35d5eeSXin Li and comments. 43*8c35d5eeSXin Li 44*8c35d5eeSXin Li </li><li>The term <em>comment</em> always refers to <em>implementation</em> comments. We do not 45*8c35d5eeSXin Li use the phrase "documentation comments", instead using the common term "Javadoc."</li> 46*8c35d5eeSXin Li</ol> 47*8c35d5eeSXin Li 48*8c35d5eeSXin Li<p>Other "terminology notes" will appear occasionally throughout the document.</p> 49*8c35d5eeSXin Li 50*8c35d5eeSXin Li<h3 id="s1.2-guide-notes">1.2 Guide notes</h3> 51*8c35d5eeSXin Li 52*8c35d5eeSXin Li<p>Example code in this document is <strong>non-normative</strong>. That is, while the examples 53*8c35d5eeSXin Liare in Google Style, they may not illustrate the <em>only</em> stylish way to represent the 54*8c35d5eeSXin Licode. Optional formatting choices made in examples should not be enforced as rules.</p> 55*8c35d5eeSXin Li 56*8c35d5eeSXin Li 57*8c35d5eeSXin Li<h2 id="s2-source-file-basics">2 Source file basics</h2> 58*8c35d5eeSXin Li 59*8c35d5eeSXin Li<h3 id="s2.1-file-name">2.1 File name</h3> 60*8c35d5eeSXin Li 61*8c35d5eeSXin Li<p>The source file name consists of the case-sensitive name of the top-level class it contains 62*8c35d5eeSXin Li(of which there is <a href="#s3.4.1-one-top-level-class">exactly one</a>), plus the 63*8c35d5eeSXin Li<code>.java</code> extension.</p> 64*8c35d5eeSXin Li 65*8c35d5eeSXin Li<h3 id="s2.2-file-encoding">2.2 File encoding: UTF-8</h3> 66*8c35d5eeSXin Li 67*8c35d5eeSXin Li<p>Source files are encoded in <strong>UTF-8</strong>.</p> 68*8c35d5eeSXin Li 69*8c35d5eeSXin Li<h3 id="s2.3-special-characters">2.3 Special characters</h3> 70*8c35d5eeSXin Li 71*8c35d5eeSXin Li<h4 id="s2.3.1-whitespace-characters">2.3.1 Whitespace characters</h4> 72*8c35d5eeSXin Li 73*8c35d5eeSXin Li<p>Aside from the line terminator sequence, the <strong>ASCII horizontal space 74*8c35d5eeSXin Licharacter</strong> (<strong>0x20</strong>) is the only whitespace character that appears 75*8c35d5eeSXin Lianywhere in a source file. This implies that:</p> 76*8c35d5eeSXin Li 77*8c35d5eeSXin Li<ol> 78*8c35d5eeSXin Li <li>All other whitespace characters in string and character literals are escaped.</li> 79*8c35d5eeSXin Li 80*8c35d5eeSXin Li <li>Tab characters are <strong>not</strong> used for indentation.</li> 81*8c35d5eeSXin Li</ol> 82*8c35d5eeSXin Li 83*8c35d5eeSXin Li<h4 id="s2.3.2-special-escape-sequences">2.3.2 Special escape sequences</h4> 84*8c35d5eeSXin Li 85*8c35d5eeSXin Li<p>For any character that has a 86*8c35d5eeSXin Li<a href="http://docs.oracle.com/javase/tutorial/java/data/characters.html"> 87*8c35d5eeSXin Li special escape sequence</a> 88*8c35d5eeSXin Li(<code class="prettyprint lang-java">\b</code>, 89*8c35d5eeSXin Li<code class="prettyprint lang-java">\t</code>, 90*8c35d5eeSXin Li<code class="prettyprint lang-java">\n</code>, 91*8c35d5eeSXin Li<code class="prettyprint lang-java">\f</code>, 92*8c35d5eeSXin Li<code class="prettyprint lang-java">\r</code>, 93*8c35d5eeSXin Li<code class="prettyprint lang-java">\"</code>, 94*8c35d5eeSXin Li<code class="prettyprint lang-java">\'</code> and 95*8c35d5eeSXin Li<code class="prettyprint lang-java">\\</code>), that sequence 96*8c35d5eeSXin Liis used rather than the corresponding octal 97*8c35d5eeSXin Li(e.g. <code class="badcode">\012</code>) or Unicode 98*8c35d5eeSXin Li(e.g. <code class="badcode">\u000a</code>) escape.</p> 99*8c35d5eeSXin Li 100*8c35d5eeSXin Li<h4 id="s2.3.3-non-ascii-characters">2.3.3 Non-ASCII characters</h4> 101*8c35d5eeSXin Li 102*8c35d5eeSXin Li<p>For the remaining non-ASCII characters, either the actual Unicode character 103*8c35d5eeSXin Li(e.g. <code class="prettyprint lang-java">∞</code>) or the equivalent Unicode escape 104*8c35d5eeSXin Li(e.g. <code class="prettyprint lang-java">\u221e</code>) is used. The choice depends only on 105*8c35d5eeSXin Liwhich makes the code <strong>easier to read and understand</strong>, although Unicode escapes 106*8c35d5eeSXin Lioutside string literals and comments are strongly discouraged.</p> 107*8c35d5eeSXin Li 108*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> In the Unicode escape case, and occasionally even when actual 109*8c35d5eeSXin LiUnicode characters are used, an explanatory comment can be very helpful.</p> 110*8c35d5eeSXin Li 111*8c35d5eeSXin Li<p>Examples:</p> 112*8c35d5eeSXin Li 113*8c35d5eeSXin Li<table> 114*8c35d5eeSXin Li <tbody><tr> 115*8c35d5eeSXin Li <th>Example</th> 116*8c35d5eeSXin Li <th>Discussion</th> 117*8c35d5eeSXin Li </tr> 118*8c35d5eeSXin Li 119*8c35d5eeSXin Li <tr> 120*8c35d5eeSXin Li <td><code class="prettyprint lang-java">String unitAbbrev = "μs";</code></td> 121*8c35d5eeSXin Li <td>Best: perfectly clear even without a comment.</td> 122*8c35d5eeSXin Li </tr> 123*8c35d5eeSXin Li 124*8c35d5eeSXin Li <tr> 125*8c35d5eeSXin Li <td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; // "μs"</code></td> 126*8c35d5eeSXin Li <td>Allowed, but there's no reason to do this.</td> 127*8c35d5eeSXin Li </tr> 128*8c35d5eeSXin Li 129*8c35d5eeSXin Li <tr> 130*8c35d5eeSXin Li <td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; 131*8c35d5eeSXin Li // Greek letter mu, "s"</code></td> 132*8c35d5eeSXin Li <td>Allowed, but awkward and prone to mistakes.</td> 133*8c35d5eeSXin Li </tr> 134*8c35d5eeSXin Li 135*8c35d5eeSXin Li <tr> 136*8c35d5eeSXin Li <td><code class="badcode">String unitAbbrev = "\u03bcs";</code></td> 137*8c35d5eeSXin Li <td>Poor: the reader has no idea what this is.</td> 138*8c35d5eeSXin Li </tr> 139*8c35d5eeSXin Li 140*8c35d5eeSXin Li <tr> 141*8c35d5eeSXin Li <td><code class="prettyprint lang-java">return '\ufeff' + content; 142*8c35d5eeSXin Li // byte order mark</code></td> 143*8c35d5eeSXin Li <td>Good: use escapes for non-printable characters, and comment if necessary.</td> 144*8c35d5eeSXin Li </tr> 145*8c35d5eeSXin Li</tbody></table> 146*8c35d5eeSXin Li 147*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> Never make your code less readable simply out of fear that 148*8c35d5eeSXin Lisome programs might not handle non-ASCII characters properly. If that should happen, those 149*8c35d5eeSXin Liprograms are <strong>broken</strong> and they must be <strong>fixed</strong>.</p> 150*8c35d5eeSXin Li 151*8c35d5eeSXin Li 152*8c35d5eeSXin Li<a name="filestructure"></a> 153*8c35d5eeSXin Li<h2 id="s3-source-file-structure">3 Source file structure</h2> 154*8c35d5eeSXin Li 155*8c35d5eeSXin Li<div> 156*8c35d5eeSXin Li<p>A source file consists of, <strong>in order</strong>:</p> 157*8c35d5eeSXin Li 158*8c35d5eeSXin Li<ol> 159*8c35d5eeSXin Li <li>License or copyright information, if present</li> 160*8c35d5eeSXin Li <li>Package statement</li> 161*8c35d5eeSXin Li <li>Import statements</li> 162*8c35d5eeSXin Li <li>Exactly one top-level class</li> 163*8c35d5eeSXin Li</ol> 164*8c35d5eeSXin Li</div> 165*8c35d5eeSXin Li 166*8c35d5eeSXin Li<p><strong>Exactly one blank line</strong> separates each section that is present.</p> 167*8c35d5eeSXin Li 168*8c35d5eeSXin Li<h3 id="s3.1-copyright-statement">3.1 License or copyright information, if present</h3> 169*8c35d5eeSXin Li 170*8c35d5eeSXin Li<p>If license or copyright information belongs in a file, it belongs here.</p> 171*8c35d5eeSXin Li 172*8c35d5eeSXin Li 173*8c35d5eeSXin Li 174*8c35d5eeSXin Li<h3 id="s3.2-package-statement">3.2 Package statement</h3> 175*8c35d5eeSXin Li 176*8c35d5eeSXin Li<p>The package statement is <strong>not line-wrapped</strong>. The column limit (Section 4.4, 177*8c35d5eeSXin Li<a href="#s4.4-column-limit">Column limit: 100</a>) does not apply to package statements.</p> 178*8c35d5eeSXin Li 179*8c35d5eeSXin Li<a name="imports"></a> 180*8c35d5eeSXin Li<h3 id="s3.3-import-statements">3.3 Import statements</h3> 181*8c35d5eeSXin Li 182*8c35d5eeSXin Li<h4 id="s3.3.1-wildcard-imports">3.3.1 No wildcard imports</h4> 183*8c35d5eeSXin Li 184*8c35d5eeSXin Li<p><strong>Wildcard imports</strong>, static or otherwise, <strong>are not used</strong>.</p> 185*8c35d5eeSXin Li 186*8c35d5eeSXin Li<h4 id="s3.3.2-import-line-wrapping">3.3.2 No line-wrapping</h4> 187*8c35d5eeSXin Li 188*8c35d5eeSXin Li<p>Import statements are <strong>not line-wrapped</strong>. The column limit (Section 4.4, 189*8c35d5eeSXin Li<a href="#s4.4-column-limit">Column limit: 100</a>) does not apply to import 190*8c35d5eeSXin Listatements.</p> 191*8c35d5eeSXin Li 192*8c35d5eeSXin Li<h4 id="s3.3.3-import-ordering-and-spacing">3.3.3 Ordering and spacing</h4> 193*8c35d5eeSXin Li 194*8c35d5eeSXin Li<p>Imports are ordered as follows:</p> 195*8c35d5eeSXin Li 196*8c35d5eeSXin Li<ol> 197*8c35d5eeSXin Li <li>All static imports in a single block.</li> 198*8c35d5eeSXin Li <li>All non-static imports in a single block.</li> 199*8c35d5eeSXin Li</ol> 200*8c35d5eeSXin Li 201*8c35d5eeSXin Li<p>If there are both static and non-static imports, a single blank line separates the two 202*8c35d5eeSXin Liblocks. There are no other blank lines between import statements.</p> 203*8c35d5eeSXin Li 204*8c35d5eeSXin Li<p>Within each block the imported names appear in ASCII sort order. (<strong>Note:</strong> 205*8c35d5eeSXin Lithis is not the same as the import <em>statements</em> being in ASCII sort order, since '.' 206*8c35d5eeSXin Lisorts before ';'.)</p> 207*8c35d5eeSXin Li 208*8c35d5eeSXin Li 209*8c35d5eeSXin Li 210*8c35d5eeSXin Li<h4 id="s3.3.4-import-class-not-static">3.3.4 No static import for classes</h4> 211*8c35d5eeSXin Li 212*8c35d5eeSXin Li<p>Static import is not used for static nested classes. They are imported with 213*8c35d5eeSXin Linormal imports.</p> 214*8c35d5eeSXin Li 215*8c35d5eeSXin Li<h3 id="s3.4-class-declaration">3.4 Class declaration</h3> 216*8c35d5eeSXin Li 217*8c35d5eeSXin Li<a name="oneclassperfile"></a> 218*8c35d5eeSXin Li<h4 id="s3.4.1-one-top-level-class">3.4.1 Exactly one top-level class declaration</h4> 219*8c35d5eeSXin Li 220*8c35d5eeSXin Li<p>Each top-level class resides in a source file of its own.</p> 221*8c35d5eeSXin Li 222*8c35d5eeSXin Li<a name="s3.4.2-class-member-ordering"></a> 223*8c35d5eeSXin Li<h4 id="s3.4.2-ordering-class-contents">3.4.2 Ordering of class contents</h4> 224*8c35d5eeSXin Li 225*8c35d5eeSXin Li<p>The order you choose for the members and initializers of your class can have a great effect on 226*8c35d5eeSXin Lilearnability. However, there's no single correct recipe for how to do it; different classes may 227*8c35d5eeSXin Liorder their contents in different ways.</p> 228*8c35d5eeSXin Li 229*8c35d5eeSXin Li<p>What is important is that each class uses <strong><em>some</em> logical order</strong>, which its 230*8c35d5eeSXin Limaintainer could explain if asked. For example, new methods are not just habitually added to the end 231*8c35d5eeSXin Liof the class, as that would yield "chronological by date added" ordering, which is not a logical 232*8c35d5eeSXin Liordering.</p> 233*8c35d5eeSXin Li 234*8c35d5eeSXin Li 235*8c35d5eeSXin Li 236*8c35d5eeSXin Li<a name="overloads"></a> 237*8c35d5eeSXin Li<h5 id="s3.4.2.1-overloads-never-split">3.4.2.1 Overloads: never split</h5> 238*8c35d5eeSXin Li 239*8c35d5eeSXin Li<p>When a class has multiple constructors, or multiple methods with the same name, these appear 240*8c35d5eeSXin Lisequentially, with no other code in between (not even private members).</p> 241*8c35d5eeSXin Li 242*8c35d5eeSXin Li<h2 id="s4-formatting">4 Formatting</h2> 243*8c35d5eeSXin Li 244*8c35d5eeSXin Li<p class="terminology"><strong>Terminology Note:</strong> <em>block-like construct</em> refers to 245*8c35d5eeSXin Lithe body of a class, method or constructor. Note that, by Section 4.8.3.1 on 246*8c35d5eeSXin Li<a href="#s4.8.3.1-array-initializers">array initializers</a>, any array initializer 247*8c35d5eeSXin Li<em>may</em> optionally be treated as if it were a block-like construct.</p> 248*8c35d5eeSXin Li 249*8c35d5eeSXin Li<a name="braces"></a> 250*8c35d5eeSXin Li<h3 id="s4.1-braces">4.1 Braces</h3> 251*8c35d5eeSXin Li 252*8c35d5eeSXin Li<h4 id="s4.1.1-braces-always-used">4.1.1 Braces are used where optional</h4> 253*8c35d5eeSXin Li 254*8c35d5eeSXin Li<p>Braces are used with 255*8c35d5eeSXin Li<code class="prettyprint lang-java">if</code>, 256*8c35d5eeSXin Li<code class="prettyprint lang-java">else</code>, 257*8c35d5eeSXin Li<code class="prettyprint lang-java">for</code>, 258*8c35d5eeSXin Li<code class="prettyprint lang-java">do</code> and 259*8c35d5eeSXin Li<code class="prettyprint lang-java">while</code> statements, even when the 260*8c35d5eeSXin Libody is empty or contains only a single statement.</p> 261*8c35d5eeSXin Li 262*8c35d5eeSXin Li<h4 id="s4.1.2-blocks-k-r-style">4.1.2 Nonempty blocks: K & R style</h4> 263*8c35d5eeSXin Li 264*8c35d5eeSXin Li<p>Braces follow the Kernighan and Ritchie style 265*8c35d5eeSXin Li("<a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a>") 266*8c35d5eeSXin Lifor <em>nonempty</em> blocks and block-like constructs:</p> 267*8c35d5eeSXin Li 268*8c35d5eeSXin Li<ul> 269*8c35d5eeSXin Li <li>No line break before the opening brace.</li> 270*8c35d5eeSXin Li 271*8c35d5eeSXin Li <li>Line break after the opening brace.</li> 272*8c35d5eeSXin Li 273*8c35d5eeSXin Li <li>Line break before the closing brace.</li> 274*8c35d5eeSXin Li 275*8c35d5eeSXin Li <li>Line break after the closing brace, <em>only if</em> that brace terminates a statement or 276*8c35d5eeSXin Li terminates the body of a method, constructor, or <em>named</em> class. 277*8c35d5eeSXin Li For example, there is <em>no</em> line break after the brace if it is followed by 278*8c35d5eeSXin Li <code class="prettyprint lang-java">else</code> or a comma.</li> 279*8c35d5eeSXin Li</ul> 280*8c35d5eeSXin Li 281*8c35d5eeSXin Li<p>Examples:</p> 282*8c35d5eeSXin Li 283*8c35d5eeSXin Li<pre class="prettyprint lang-java">return () -> { 284*8c35d5eeSXin Li while (condition()) { 285*8c35d5eeSXin Li method(); 286*8c35d5eeSXin Li } 287*8c35d5eeSXin Li}; 288*8c35d5eeSXin Li 289*8c35d5eeSXin Lireturn new MyClass() { 290*8c35d5eeSXin Li @Override public void method() { 291*8c35d5eeSXin Li if (condition()) { 292*8c35d5eeSXin Li try { 293*8c35d5eeSXin Li something(); 294*8c35d5eeSXin Li } catch (ProblemException e) { 295*8c35d5eeSXin Li recover(); 296*8c35d5eeSXin Li } 297*8c35d5eeSXin Li } else if (otherCondition()) { 298*8c35d5eeSXin Li somethingElse(); 299*8c35d5eeSXin Li } else { 300*8c35d5eeSXin Li lastThing(); 301*8c35d5eeSXin Li } 302*8c35d5eeSXin Li } 303*8c35d5eeSXin Li}; 304*8c35d5eeSXin Li</pre> 305*8c35d5eeSXin Li 306*8c35d5eeSXin Li<p>A few exceptions for enum classes are given in Section 4.8.1, 307*8c35d5eeSXin Li<a href="#s4.8.1-enum-classes">Enum classes</a>.</p> 308*8c35d5eeSXin Li 309*8c35d5eeSXin Li<a name="emptyblocks"></a> 310*8c35d5eeSXin Li<h4 id="s4.1.3-braces-empty-blocks">4.1.3 Empty blocks: may be concise</h4> 311*8c35d5eeSXin Li 312*8c35d5eeSXin Li<p>An empty block or block-like construct may be in K & R style (as described in 313*8c35d5eeSXin Li<a href="#s4.1.2-blocks-k-r-style">Section 4.1.2</a>). Alternatively, it may be closed immediately 314*8c35d5eeSXin Liafter it is opened, with no characters or line break in between 315*8c35d5eeSXin Li(<code class="prettyprint lang-java">{}</code>), <strong>unless</strong> it is part of a 316*8c35d5eeSXin Li<em>multi-block statement</em> (one that directly contains multiple blocks: 317*8c35d5eeSXin Li<code class="prettyprint lang-java">if/else</code> or 318*8c35d5eeSXin Li<code class="prettyprint lang-java">try/catch/finally</code>).</p> 319*8c35d5eeSXin Li 320*8c35d5eeSXin Li<p>Examples:</p> 321*8c35d5eeSXin Li 322*8c35d5eeSXin Li<pre class="prettyprint lang-java"> // This is acceptable 323*8c35d5eeSXin Li void doNothing() {} 324*8c35d5eeSXin Li 325*8c35d5eeSXin Li // This is equally acceptable 326*8c35d5eeSXin Li void doNothingElse() { 327*8c35d5eeSXin Li } 328*8c35d5eeSXin Li</pre> 329*8c35d5eeSXin Li<pre class="prettyprint lang-java badcode"> // This is not acceptable: No concise empty blocks in a multi-block statement 330*8c35d5eeSXin Li try { 331*8c35d5eeSXin Li doSomething(); 332*8c35d5eeSXin Li } catch (Exception e) {} 333*8c35d5eeSXin Li</pre> 334*8c35d5eeSXin Li 335*8c35d5eeSXin Li<h3 id="s4.2-block-indentation">4.2 Block indentation: +2 spaces</h3> 336*8c35d5eeSXin Li 337*8c35d5eeSXin Li<p>Each time a new block or block-like construct is opened, the indent increases by two 338*8c35d5eeSXin Lispaces. When the block ends, the indent returns to the previous indent level. The indent level 339*8c35d5eeSXin Liapplies to both code and comments throughout the block. (See the example in Section 4.1.2, 340*8c35d5eeSXin Li<a href="#s4.1.2-blocks-k-r-style">Nonempty blocks: K & R Style</a>.)</p> 341*8c35d5eeSXin Li 342*8c35d5eeSXin Li<h3 id="s4.3-one-statement-per-line">4.3 One statement per line</h3> 343*8c35d5eeSXin Li 344*8c35d5eeSXin Li<p>Each statement is followed by a line break.</p> 345*8c35d5eeSXin Li 346*8c35d5eeSXin Li<a name="columnlimit"></a> 347*8c35d5eeSXin Li<h3 id="s4.4-column-limit">4.4 Column limit: 100</h3> 348*8c35d5eeSXin Li 349*8c35d5eeSXin Li<p>Java code has a column limit of 100 characters. A "character" means any Unicode code point. 350*8c35d5eeSXin LiExcept as noted below, any line that would exceed this limit must be line-wrapped, as explained in 351*8c35d5eeSXin LiSection 4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>. 352*8c35d5eeSXin Li</p> 353*8c35d5eeSXin Li 354*8c35d5eeSXin Li<p class="tip">Each Unicode code point counts as one character, even if its display width is 355*8c35d5eeSXin Ligreater or less. For example, if using 356*8c35d5eeSXin Li<a href="https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms">fullwidth characters</a>, 357*8c35d5eeSXin Liyou may choose to wrap the line earlier than where this rule strictly requires.</p> 358*8c35d5eeSXin Li 359*8c35d5eeSXin Li<p><strong>Exceptions:</strong></p> 360*8c35d5eeSXin Li 361*8c35d5eeSXin Li<ol> 362*8c35d5eeSXin Li <li>Lines where obeying the column limit is not possible (for example, a long URL in Javadoc, 363*8c35d5eeSXin Li or a long JSNI method reference).</li> 364*8c35d5eeSXin Li 365*8c35d5eeSXin Li <li><code class="prettyprint lang-java">package</code> and 366*8c35d5eeSXin Li <code class="prettyprint lang-java">import</code> statements (see Sections 367*8c35d5eeSXin Li 3.2 <a href="#s3.2-package-statement">Package statement</a> and 368*8c35d5eeSXin Li 3.3 <a href="#s3.3-import-statements">Import statements</a>).</li> 369*8c35d5eeSXin Li 370*8c35d5eeSXin Li <li>Command lines in a comment that may be cut-and-pasted into a shell.</li> 371*8c35d5eeSXin Li</ol> 372*8c35d5eeSXin Li 373*8c35d5eeSXin Li<h3 id="s4.5-line-wrapping">4.5 Line-wrapping</h3> 374*8c35d5eeSXin Li 375*8c35d5eeSXin Li<p class="terminology"><strong>Terminology Note:</strong> When code that might otherwise legally 376*8c35d5eeSXin Lioccupy a single line is divided into multiple lines, this activity is called 377*8c35d5eeSXin Li<em>line-wrapping</em>.</p> 378*8c35d5eeSXin Li 379*8c35d5eeSXin Li<p>There is no comprehensive, deterministic formula showing <em>exactly</em> how to line-wrap in 380*8c35d5eeSXin Lievery situation. Very often there are several valid ways to line-wrap the same piece of code.</p> 381*8c35d5eeSXin Li 382*8c35d5eeSXin Li<p class="note"><strong>Note:</strong> While the typical reason for line-wrapping is to avoid 383*8c35d5eeSXin Lioverflowing the column limit, even code that would in fact fit within the column limit <em>may</em> 384*8c35d5eeSXin Libe line-wrapped at the author's discretion.</p> 385*8c35d5eeSXin Li 386*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> Extracting a method or local variable may solve the problem 387*8c35d5eeSXin Liwithout the need to line-wrap.</p> 388*8c35d5eeSXin Li 389*8c35d5eeSXin Li<h4 id="s4.5.1-line-wrapping-where-to-break">4.5.1 Where to break</h4> 390*8c35d5eeSXin Li 391*8c35d5eeSXin Li<p>The prime directive of line-wrapping is: prefer to break at a 392*8c35d5eeSXin Li<strong>higher syntactic level</strong>. Also:</p> 393*8c35d5eeSXin Li 394*8c35d5eeSXin Li<ol> 395*8c35d5eeSXin Li <li>When a line is broken at a <em>non-assignment</em> operator the break comes <em>before</em> 396*8c35d5eeSXin Li the symbol. (Note that this is not the same practice used in Google style for other languages, 397*8c35d5eeSXin Li such as C++ and JavaScript.) 398*8c35d5eeSXin Li <ul> 399*8c35d5eeSXin Li <li>This also applies to the following "operator-like" symbols: 400*8c35d5eeSXin Li <ul> 401*8c35d5eeSXin Li <li>the dot separator (<code class="prettyprint lang-java">.</code>)</li> 402*8c35d5eeSXin Li <li>the two colons of a method reference 403*8c35d5eeSXin Li (<code class="prettyprint lang-java">::</code>)</li> 404*8c35d5eeSXin Li <li>an ampersand in a type bound 405*8c35d5eeSXin Li (<code class="prettyprint lang-java"><T extends Foo & Bar></code>)</li> 406*8c35d5eeSXin Li <li>a pipe in a catch block 407*8c35d5eeSXin Li (<code class="prettyprint lang-java">catch (FooException | BarException e)</code>).</li> 408*8c35d5eeSXin Li </ul> 409*8c35d5eeSXin Li </li> 410*8c35d5eeSXin Li </ul> 411*8c35d5eeSXin Li </li> 412*8c35d5eeSXin Li 413*8c35d5eeSXin Li <li>When a line is broken at an <em>assignment</em> operator the break typically comes 414*8c35d5eeSXin Li <em>after</em> the symbol, but either way is acceptable. 415*8c35d5eeSXin Li <ul> 416*8c35d5eeSXin Li <li>This also applies to the "assignment-operator-like" colon in an enhanced 417*8c35d5eeSXin Li <code class="prettyprint lang-java">for</code> ("foreach") statement.</li> 418*8c35d5eeSXin Li </ul> 419*8c35d5eeSXin Li </li> 420*8c35d5eeSXin Li 421*8c35d5eeSXin Li <li>A method or constructor name stays attached to the open parenthesis 422*8c35d5eeSXin Li (<code class="prettyprint lang-java">(</code>) that follows it.</li> 423*8c35d5eeSXin Li 424*8c35d5eeSXin Li <li>A comma (<code class="prettyprint lang-java">,</code>) stays attached to the token that 425*8c35d5eeSXin Li precedes it.</li> 426*8c35d5eeSXin Li 427*8c35d5eeSXin Li <li>A line is never broken adjacent to the arrow in a lambda, except that a 428*8c35d5eeSXin Li break may come immediately after the arrow if the body of the lambda consists 429*8c35d5eeSXin Li of a single unbraced expression. Examples: 430*8c35d5eeSXin Li<pre class="prettyprint lang-java">MyLambda<String, Long, Object> lambda = 431*8c35d5eeSXin Li (String label, Long value, Object obj) -> { 432*8c35d5eeSXin Li ... 433*8c35d5eeSXin Li }; 434*8c35d5eeSXin Li 435*8c35d5eeSXin LiPredicate<String> predicate = str -> 436*8c35d5eeSXin Li longExpressionInvolving(str); 437*8c35d5eeSXin Li</pre> 438*8c35d5eeSXin Li </li> 439*8c35d5eeSXin Li</ol> 440*8c35d5eeSXin Li 441*8c35d5eeSXin Li<p class="note"><strong>Note:</strong> The primary goal for line wrapping is to have clear 442*8c35d5eeSXin Licode, <em>not necessarily</em> code that fits in the smallest number of lines.</p> 443*8c35d5eeSXin Li 444*8c35d5eeSXin Li<a name="indentation"></a> 445*8c35d5eeSXin Li<h4 id="s4.5.2-line-wrapping-indent">4.5.2 Indent continuation lines at least +4 spaces</h4> 446*8c35d5eeSXin Li 447*8c35d5eeSXin Li<p>When line-wrapping, each line after the first (each <em>continuation line</em>) is indented 448*8c35d5eeSXin Liat least +4 from the original line.</p> 449*8c35d5eeSXin Li 450*8c35d5eeSXin Li<p>When there are multiple continuation lines, indentation may be varied beyond +4 as 451*8c35d5eeSXin Lidesired. In general, two continuation lines use the same indentation level if and only if they 452*8c35d5eeSXin Libegin with syntactically parallel elements.</p> 453*8c35d5eeSXin Li 454*8c35d5eeSXin Li<p>Section 4.6.3 on <a href="#s4.6.3-horizontal-alignment">Horizontal alignment</a> addresses 455*8c35d5eeSXin Lithe discouraged practice of using a variable number of spaces to align certain tokens with 456*8c35d5eeSXin Liprevious lines.</p> 457*8c35d5eeSXin Li 458*8c35d5eeSXin Li<h3 id="s4.6-whitespace">4.6 Whitespace</h3> 459*8c35d5eeSXin Li 460*8c35d5eeSXin Li<h4 id="s4.6.1-vertical-whitespace">4.6.1 Vertical Whitespace</h4> 461*8c35d5eeSXin Li 462*8c35d5eeSXin Li<p>A single blank line always appears:</p> 463*8c35d5eeSXin Li 464*8c35d5eeSXin Li<ol> 465*8c35d5eeSXin Li <li><em>Between</em> consecutive members or initializers of a class: fields, constructors, 466*8c35d5eeSXin Li methods, nested classes, static initializers, and instance initializers. 467*8c35d5eeSXin Li <ul> 468*8c35d5eeSXin Li <li><span class="exception"><strong>Exception:</strong> A blank line between two consecutive 469*8c35d5eeSXin Li fields (having no other code between them) is optional. Such blank lines are used as needed to 470*8c35d5eeSXin Li create <em>logical groupings</em> of fields.</span></li> 471*8c35d5eeSXin Li <li><span class="exception"><strong>Exception:</strong> Blank lines between enum constants are 472*8c35d5eeSXin Li covered in <a href="#s4.8.1-enum-classes">Section 4.8.1</a>.</span></li> 473*8c35d5eeSXin Li </ul> 474*8c35d5eeSXin Li </li> 475*8c35d5eeSXin Li 476*8c35d5eeSXin Li <li>As required by other sections of this document (such as Section 3, 477*8c35d5eeSXin Li <a href="#s3-source-file-structure">Source file structure</a>, and Section 3.3, 478*8c35d5eeSXin Li <a href="#s3.3-import-statements">Import statements</a>).</li> 479*8c35d5eeSXin Li</ol> 480*8c35d5eeSXin Li 481*8c35d5eeSXin Li<p>A single blank line may also appear anywhere it improves readability, for example between 482*8c35d5eeSXin Listatements to organize the code into logical subsections. A blank line before the first member or 483*8c35d5eeSXin Liinitializer, or after the last member or initializer of the class, is neither encouraged nor 484*8c35d5eeSXin Lidiscouraged. 485*8c35d5eeSXin Li 486*8c35d5eeSXin Li</p><p><em>Multiple</em> consecutive blank lines are permitted, but never required (or encouraged).</p> 487*8c35d5eeSXin Li 488*8c35d5eeSXin Li<h4 id="s4.6.2-horizontal-whitespace">4.6.2 Horizontal whitespace</h4> 489*8c35d5eeSXin Li 490*8c35d5eeSXin Li<p>Beyond where required by the language or other style rules, and apart from literals, comments and 491*8c35d5eeSXin LiJavadoc, a single ASCII space also appears in the following places <strong>only</strong>.</p> 492*8c35d5eeSXin Li 493*8c35d5eeSXin Li<ol> 494*8c35d5eeSXin Li <li>Separating any reserved word, such as 495*8c35d5eeSXin Li <code class="prettyprint lang-java">if</code>, 496*8c35d5eeSXin Li <code class="prettyprint lang-java">for</code> or 497*8c35d5eeSXin Li <code class="prettyprint lang-java">catch</code>, from an open parenthesis 498*8c35d5eeSXin Li (<code class="prettyprint lang-java">(</code>) 499*8c35d5eeSXin Li that follows it on that line</li> 500*8c35d5eeSXin Li 501*8c35d5eeSXin Li <li>Separating any reserved word, such as 502*8c35d5eeSXin Li <code class="prettyprint lang-java">else</code> or 503*8c35d5eeSXin Li <code class="prettyprint lang-java">catch</code>, from a closing curly brace 504*8c35d5eeSXin Li (<code class="prettyprint lang-java">}</code>) that precedes it on that line</li> 505*8c35d5eeSXin Li 506*8c35d5eeSXin Li <li>Before any open curly brace 507*8c35d5eeSXin Li (<code class="prettyprint lang-java">{</code>), with two exceptions: 508*8c35d5eeSXin Li <ul> 509*8c35d5eeSXin Li <li><code class="prettyprint lang-java">@SomeAnnotation({a, b})</code> (no space is used)</li> 510*8c35d5eeSXin Li 511*8c35d5eeSXin Li <li><code class="prettyprint lang-java">String[][] x = {{"foo"}};</code> (no space is required 512*8c35d5eeSXin Li between <code class="prettyprint lang-java">{{</code>, by item 8 below)</li> 513*8c35d5eeSXin Li </ul> 514*8c35d5eeSXin Li </li> 515*8c35d5eeSXin Li 516*8c35d5eeSXin Li <li>On both sides of any binary or ternary operator. This also applies to the following 517*8c35d5eeSXin Li "operator-like" symbols: 518*8c35d5eeSXin Li <ul> 519*8c35d5eeSXin Li <li>the ampersand in a conjunctive type bound: 520*8c35d5eeSXin Li <code class="prettyprint lang-java"><T extends Foo & Bar></code></li> 521*8c35d5eeSXin Li 522*8c35d5eeSXin Li <li>the pipe for a catch block that handles multiple exceptions: 523*8c35d5eeSXin Li <code class="prettyprint lang-java">catch (FooException | BarException e)</code></li> 524*8c35d5eeSXin Li 525*8c35d5eeSXin Li <li>the colon (<code class="prettyprint lang-java">:</code>) in an enhanced 526*8c35d5eeSXin Li <code class="prettyprint lang-java">for</code> ("foreach") statement</li> 527*8c35d5eeSXin Li 528*8c35d5eeSXin Li <li>the arrow in a lambda expression: 529*8c35d5eeSXin Li <code class="prettyprint lang-java">(String str) -> str.length()</code></li> 530*8c35d5eeSXin Li </ul> 531*8c35d5eeSXin Li but not 532*8c35d5eeSXin Li 533*8c35d5eeSXin Li <ul> 534*8c35d5eeSXin Li <li>the two colons (<code class="prettyprint lang-java">::</code>) of a method reference, which 535*8c35d5eeSXin Li is written like <code class="prettyprint lang-java">Object::toString</code></li> 536*8c35d5eeSXin Li <li>the dot separator (<code class="prettyprint lang-java">.</code>), which is written like 537*8c35d5eeSXin Li <code class="prettyprint lang-java">object.toString()</code></li> 538*8c35d5eeSXin Li </ul> 539*8c35d5eeSXin Li </li> 540*8c35d5eeSXin Li 541*8c35d5eeSXin Li <li>After <code class="prettyprint lang-java">,:;</code> or the closing parenthesis 542*8c35d5eeSXin Li (<code class="prettyprint lang-java">)</code>) of a cast</li> 543*8c35d5eeSXin Li 544*8c35d5eeSXin Li <li>On both sides of the double slash (<code class="prettyprint lang-java">//</code>) that 545*8c35d5eeSXin Li begins an end-of-line comment. Here, multiple spaces are allowed, but not required.</li> 546*8c35d5eeSXin Li 547*8c35d5eeSXin Li <li>Between the type and variable of a declaration: 548*8c35d5eeSXin Li <code class="prettyprint lang-java">List<String> list</code></li> 549*8c35d5eeSXin Li 550*8c35d5eeSXin Li <li><em>Optional</em> just inside both braces of an array initializer 551*8c35d5eeSXin Li <ul> 552*8c35d5eeSXin Li <li><code class="prettyprint lang-java">new int[] {5, 6}</code> and 553*8c35d5eeSXin Li <code class="prettyprint lang-java">new int[] { 5, 6 }</code> are both valid</li> 554*8c35d5eeSXin Li </ul> 555*8c35d5eeSXin Li </li> 556*8c35d5eeSXin Li 557*8c35d5eeSXin Li <li>Between a type annotation and <code class="prettyprint lang-java">[]</code> or 558*8c35d5eeSXin Li <code class="prettyprint lang-java">...</code>.</li> 559*8c35d5eeSXin Li</ol> 560*8c35d5eeSXin Li 561*8c35d5eeSXin Li<p>This rule is never interpreted as requiring or forbidding additional space at the start or 562*8c35d5eeSXin Liend of a line; it addresses only <em>interior</em> space.</p> 563*8c35d5eeSXin Li 564*8c35d5eeSXin Li<h4 id="s4.6.3-horizontal-alignment">4.6.3 Horizontal alignment: never required</h4> 565*8c35d5eeSXin Li 566*8c35d5eeSXin Li<p class="terminology"><strong>Terminology Note:</strong> <em>Horizontal alignment</em> is the 567*8c35d5eeSXin Lipractice of adding a variable number of additional spaces in your code with the goal of making 568*8c35d5eeSXin Licertain tokens appear directly below certain other tokens on previous lines.</p> 569*8c35d5eeSXin Li 570*8c35d5eeSXin Li<p>This practice is permitted, but is <strong>never required</strong> by Google Style. It is not 571*8c35d5eeSXin Lieven required to <em>maintain</em> horizontal alignment in places where it was already used.</p> 572*8c35d5eeSXin Li 573*8c35d5eeSXin Li<p>Here is an example without alignment, then using alignment:</p> 574*8c35d5eeSXin Li 575*8c35d5eeSXin Li<pre class="prettyprint lang-java">private int x; // this is fine 576*8c35d5eeSXin Liprivate Color color; // this too 577*8c35d5eeSXin Li 578*8c35d5eeSXin Liprivate int x; // permitted, but future edits 579*8c35d5eeSXin Liprivate Color color; // may leave it unaligned 580*8c35d5eeSXin Li</pre> 581*8c35d5eeSXin Li 582*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> Alignment can aid readability, but it creates problems for 583*8c35d5eeSXin Lifuture maintenance. Consider a future change that needs to touch just one line. This change may 584*8c35d5eeSXin Lileave the formerly-pleasing formatting mangled, and that is <strong>allowed</strong>. More often 585*8c35d5eeSXin Liit prompts the coder (perhaps you) to adjust whitespace on nearby lines as well, possibly 586*8c35d5eeSXin Litriggering a cascading series of reformattings. That one-line change now has a "blast radius." 587*8c35d5eeSXin LiThis can at worst result in pointless busywork, but at best it still corrupts version history 588*8c35d5eeSXin Liinformation, slows down reviewers and exacerbates merge conflicts.</p> 589*8c35d5eeSXin Li 590*8c35d5eeSXin Li<a name="parentheses"></a> 591*8c35d5eeSXin Li<h3 id="s4.7-grouping-parentheses">4.7 Grouping parentheses: recommended</h3> 592*8c35d5eeSXin Li 593*8c35d5eeSXin Li<p>Optional grouping parentheses are omitted only when author and reviewer agree that there is no 594*8c35d5eeSXin Lireasonable chance the code will be misinterpreted without them, nor would they have made the code 595*8c35d5eeSXin Lieasier to read. It is <em>not</em> reasonable to assume that every reader has the entire Java 596*8c35d5eeSXin Lioperator precedence table memorized.</p> 597*8c35d5eeSXin Li 598*8c35d5eeSXin Li<h3 id="s4.8-specific-constructs">4.8 Specific constructs</h3> 599*8c35d5eeSXin Li 600*8c35d5eeSXin Li<h4 id="s4.8.1-enum-classes">4.8.1 Enum classes</h4> 601*8c35d5eeSXin Li 602*8c35d5eeSXin Li<p>After each comma that follows an enum constant, a line break is optional. Additional blank 603*8c35d5eeSXin Lilines (usually just one) are also allowed. This is one possibility: 604*8c35d5eeSXin Li 605*8c35d5eeSXin Li</p><pre class="prettyprint lang-java">private enum Answer { 606*8c35d5eeSXin Li YES { 607*8c35d5eeSXin Li @Override public String toString() { 608*8c35d5eeSXin Li return "yes"; 609*8c35d5eeSXin Li } 610*8c35d5eeSXin Li }, 611*8c35d5eeSXin Li 612*8c35d5eeSXin Li NO, 613*8c35d5eeSXin Li MAYBE 614*8c35d5eeSXin Li} 615*8c35d5eeSXin Li</pre> 616*8c35d5eeSXin Li 617*8c35d5eeSXin Li<p>An enum class with no methods and no documentation on its constants may optionally be formatted 618*8c35d5eeSXin Lias if it were an array initializer (see Section 4.8.3.1 on 619*8c35d5eeSXin Li<a href="#s4.8.3.1-array-initializers">array initializers</a>).</p> 620*8c35d5eeSXin Li 621*8c35d5eeSXin Li<pre class="prettyprint lang-java">private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS } 622*8c35d5eeSXin Li</pre> 623*8c35d5eeSXin Li 624*8c35d5eeSXin Li<p>Since enum classes <em>are classes</em>, all other rules for formatting classes apply.</p> 625*8c35d5eeSXin Li 626*8c35d5eeSXin Li<a name="localvariables"></a> 627*8c35d5eeSXin Li<h4 id="s4.8.2-variable-declarations">4.8.2 Variable declarations</h4> 628*8c35d5eeSXin Li 629*8c35d5eeSXin Li<h5 id="s4.8.2.1-variables-per-declaration">4.8.2.1 One variable per declaration</h5> 630*8c35d5eeSXin Li 631*8c35d5eeSXin Li<p>Every variable declaration (field or local) declares only one variable: declarations such as 632*8c35d5eeSXin Li<code class="badcode">int a, b;</code> are not used.</p> 633*8c35d5eeSXin Li 634*8c35d5eeSXin Li<p><strong>Exception:</strong> Multiple variable declarations are acceptable in the header of a 635*8c35d5eeSXin Li<code class="prettyprint lang-java">for</code> loop.</p> 636*8c35d5eeSXin Li 637*8c35d5eeSXin Li<h5 id="s4.8.2.2-variables-limited-scope">4.8.2.2 Declared when needed</h5> 638*8c35d5eeSXin Li 639*8c35d5eeSXin Li<p>Local variables are <strong>not</strong> habitually declared at the start of their containing 640*8c35d5eeSXin Liblock or block-like construct. Instead, local variables are declared close to the point they are 641*8c35d5eeSXin Lifirst used (within reason), to minimize their scope. Local variable declarations typically have 642*8c35d5eeSXin Liinitializers, or are initialized immediately after declaration.</p> 643*8c35d5eeSXin Li 644*8c35d5eeSXin Li<h4 id="s4.8.3-arrays">4.8.3 Arrays</h4> 645*8c35d5eeSXin Li 646*8c35d5eeSXin Li<h5 id="s4.8.3.1-array-initializers">4.8.3.1 Array initializers: can be "block-like"</h5> 647*8c35d5eeSXin Li 648*8c35d5eeSXin Li<p>Any array initializer may <em>optionally</em> be formatted as if it were a "block-like 649*8c35d5eeSXin Liconstruct." For example, the following are all valid (<strong>not</strong> an exhaustive 650*8c35d5eeSXin Lilist):</p> 651*8c35d5eeSXin Li 652*8c35d5eeSXin Li<pre class="prettyprint lang-java">new int[] { new int[] { 653*8c35d5eeSXin Li 0, 1, 2, 3 0, 654*8c35d5eeSXin Li} 1, 655*8c35d5eeSXin Li 2, 656*8c35d5eeSXin Linew int[] { 3, 657*8c35d5eeSXin Li 0, 1, } 658*8c35d5eeSXin Li 2, 3 659*8c35d5eeSXin Li} new int[] 660*8c35d5eeSXin Li {0, 1, 2, 3} 661*8c35d5eeSXin Li</pre> 662*8c35d5eeSXin Li 663*8c35d5eeSXin Li<h5 id="s4.8.3.2-array-declarations">4.8.3.2 No C-style array declarations</h5> 664*8c35d5eeSXin Li 665*8c35d5eeSXin Li<p>The square brackets form a part of the <em>type</em>, not the variable: 666*8c35d5eeSXin Li<code class="prettyprint lang-java">String[] args</code>, not 667*8c35d5eeSXin Li<code class="badcode">String args[]</code>.</p> 668*8c35d5eeSXin Li 669*8c35d5eeSXin Li<h4 id="s4.8.4-switch">4.8.4 Switch statements</h4> 670*8c35d5eeSXin Li 671*8c35d5eeSXin Li 672*8c35d5eeSXin Li 673*8c35d5eeSXin Li<p class="terminology"><strong>Terminology Note:</strong> Inside the braces of a 674*8c35d5eeSXin Li<em>switch block</em> are one or more <em>statement groups</em>. Each statement group consists of 675*8c35d5eeSXin Lione or more <em>switch labels</em> (either <code class="prettyprint lang-java">case FOO:</code> or 676*8c35d5eeSXin Li<code class="prettyprint lang-java">default:</code>), followed by one or more statements (or, for 677*8c35d5eeSXin Lithe <em>last</em> statement group, <em>zero</em> or more statements).</p> 678*8c35d5eeSXin Li 679*8c35d5eeSXin Li<h5 id="s4.8.4.1-switch-indentation">4.8.4.1 Indentation</h5> 680*8c35d5eeSXin Li 681*8c35d5eeSXin Li<p>As with any other block, the contents of a switch block are indented +2.</p> 682*8c35d5eeSXin Li 683*8c35d5eeSXin Li<p>After a switch label, there is a line break, and the indentation level is increased +2, exactly 684*8c35d5eeSXin Lias if a block were being opened. The following switch label returns to the previous indentation 685*8c35d5eeSXin Lilevel, as if a block had been closed.</p> 686*8c35d5eeSXin Li 687*8c35d5eeSXin Li<a name="fallthrough"></a> 688*8c35d5eeSXin Li<h5 id="s4.8.4.2-switch-fall-through">4.8.4.2 Fall-through: commented</h5> 689*8c35d5eeSXin Li 690*8c35d5eeSXin Li<p>Within a switch block, each statement group either terminates abruptly (with a 691*8c35d5eeSXin Li<code class="prettyprint lang-java">break</code>, 692*8c35d5eeSXin Li<code class="prettyprint lang-java">continue</code>, 693*8c35d5eeSXin Li<code class="prettyprint lang-java">return</code> or thrown exception), or is marked with a comment 694*8c35d5eeSXin Lito indicate that execution will or <em>might</em> continue into the next statement group. Any 695*8c35d5eeSXin Licomment that communicates the idea of fall-through is sufficient (typically 696*8c35d5eeSXin Li<code class="prettyprint lang-java">// fall through</code>). This special comment is not required in 697*8c35d5eeSXin Lithe last statement group of the switch block. Example:</p> 698*8c35d5eeSXin Li 699*8c35d5eeSXin Li<pre class="prettyprint lang-java">switch (input) { 700*8c35d5eeSXin Li case 1: 701*8c35d5eeSXin Li case 2: 702*8c35d5eeSXin Li prepareOneOrTwo(); 703*8c35d5eeSXin Li // fall through 704*8c35d5eeSXin Li case 3: 705*8c35d5eeSXin Li handleOneTwoOrThree(); 706*8c35d5eeSXin Li break; 707*8c35d5eeSXin Li default: 708*8c35d5eeSXin Li handleLargeNumber(input); 709*8c35d5eeSXin Li} 710*8c35d5eeSXin Li</pre> 711*8c35d5eeSXin Li 712*8c35d5eeSXin Li<p>Notice that no comment is needed after <code class="prettyprint lang-java">case 1:</code>, only 713*8c35d5eeSXin Liat the end of the statement group.</p> 714*8c35d5eeSXin Li 715*8c35d5eeSXin Li<h5 id="s4.8.4.3-switch-default">4.8.4.3 The <code>default</code> case is present</h5> 716*8c35d5eeSXin Li 717*8c35d5eeSXin Li<p>Each switch statement includes a <code class="prettyprint lang-java">default</code> statement 718*8c35d5eeSXin Ligroup, even if it contains no code.</p> 719*8c35d5eeSXin Li 720*8c35d5eeSXin Li<p><strong>Exception:</strong> A switch statement for an <code>enum</code> type <em>may</em> omit 721*8c35d5eeSXin Lithe <code class="prettyprint lang-java">default</code> statement group, <em>if</em> it includes 722*8c35d5eeSXin Liexplicit cases covering <em>all</em> possible values of that type. This enables IDEs or other static 723*8c35d5eeSXin Lianalysis tools to issue a warning if any cases were missed. 724*8c35d5eeSXin Li 725*8c35d5eeSXin Li</p> 726*8c35d5eeSXin Li 727*8c35d5eeSXin Li<a name="annotations"></a> 728*8c35d5eeSXin Li<h4 id="s4.8.5-annotations">4.8.5 Annotations</h4> 729*8c35d5eeSXin Li 730*8c35d5eeSXin Li<p>Annotations applying to a class, method or constructor appear immediately after the 731*8c35d5eeSXin Lidocumentation block, and each annotation is listed on a line of its own (that is, one annotation 732*8c35d5eeSXin Liper line). These line breaks do not constitute line-wrapping (Section 733*8c35d5eeSXin Li4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>), so the indentation level is not 734*8c35d5eeSXin Liincreased. Example:</p> 735*8c35d5eeSXin Li 736*8c35d5eeSXin Li<pre class="prettyprint lang-java">@Override 737*8c35d5eeSXin Li@Nullable 738*8c35d5eeSXin Lipublic String getNameIfPresent() { ... } 739*8c35d5eeSXin Li</pre> 740*8c35d5eeSXin Li 741*8c35d5eeSXin Li<p class="exception"><strong>Exception:</strong> A <em>single</em> parameterless annotation 742*8c35d5eeSXin Li<em>may</em> instead appear together with the first line of the signature, for example:</p> 743*8c35d5eeSXin Li 744*8c35d5eeSXin Li<pre class="prettyprint lang-java">@Override public int hashCode() { ... } 745*8c35d5eeSXin Li</pre> 746*8c35d5eeSXin Li 747*8c35d5eeSXin Li<p>Annotations applying to a field also appear immediately after the documentation block, but in 748*8c35d5eeSXin Lithis case, <em>multiple</em> annotations (possibly parameterized) may be listed on the same line; 749*8c35d5eeSXin Lifor example:</p> 750*8c35d5eeSXin Li 751*8c35d5eeSXin Li<pre class="prettyprint lang-java">@Partial @Mock DataLoader loader; 752*8c35d5eeSXin Li</pre> 753*8c35d5eeSXin Li 754*8c35d5eeSXin Li<p>There are no specific rules for formatting annotations on parameters, local variables, or types. 755*8c35d5eeSXin Li</p> 756*8c35d5eeSXin Li 757*8c35d5eeSXin Li<a name="comments"></a> 758*8c35d5eeSXin Li<h4 id="s4.8.6-comments">4.8.6 Comments</h4> 759*8c35d5eeSXin Li 760*8c35d5eeSXin Li<p>This section addresses <em>implementation comments</em>. Javadoc is addressed separately in 761*8c35d5eeSXin LiSection 7, <a href="#s7-javadoc">Javadoc</a>.</p> 762*8c35d5eeSXin Li 763*8c35d5eeSXin Li<p>Any line break may be preceded by arbitrary whitespace followed by an implementation comment. 764*8c35d5eeSXin LiSuch a comment renders the line non-blank.</p> 765*8c35d5eeSXin Li 766*8c35d5eeSXin Li<h5 id="s4.8.6.1-block-comment-style">4.8.6.1 Block comment style</h5> 767*8c35d5eeSXin Li 768*8c35d5eeSXin Li<p>Block comments are indented at the same level as the surrounding code. They may be in 769*8c35d5eeSXin Li<code class="prettyprint lang-java">/* ... */</code> style or 770*8c35d5eeSXin Li<code class="prettyprint lang-java">// ...</code> style. For multi-line 771*8c35d5eeSXin Li<code class="prettyprint lang-java">/* ... */</code> comments, subsequent lines must start with 772*8c35d5eeSXin Li<code>*</code> aligned with the <code>*</code> on the previous line.</p> 773*8c35d5eeSXin Li 774*8c35d5eeSXin Li<pre class="prettyprint lang-java">/* 775*8c35d5eeSXin Li * This is // And so /* Or you can 776*8c35d5eeSXin Li * okay. // is this. * even do this. */ 777*8c35d5eeSXin Li */ 778*8c35d5eeSXin Li</pre> 779*8c35d5eeSXin Li 780*8c35d5eeSXin Li 781*8c35d5eeSXin Li<p>Comments are not enclosed in boxes drawn with asterisks or other characters.</p> 782*8c35d5eeSXin Li 783*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> When writing multi-line comments, use the 784*8c35d5eeSXin Li<code class="prettyprint lang-java">/* ... */</code> style if you want automatic code formatters to 785*8c35d5eeSXin Lire-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in 786*8c35d5eeSXin Li<code class="prettyprint lang-java">// ...</code> style comment blocks.</p> 787*8c35d5eeSXin Li 788*8c35d5eeSXin Li 789*8c35d5eeSXin Li 790*8c35d5eeSXin Li<a name="modifiers"></a> 791*8c35d5eeSXin Li<h4 id="s4.8.7-modifiers">4.8.7 Modifiers</h4> 792*8c35d5eeSXin Li 793*8c35d5eeSXin Li<p>Class and member modifiers, when present, appear in the order 794*8c35d5eeSXin Lirecommended by the Java Language Specification: 795*8c35d5eeSXin Li</p> 796*8c35d5eeSXin Li 797*8c35d5eeSXin Li<pre>public protected private abstract default static final transient volatile synchronized native strictfp 798*8c35d5eeSXin Li</pre> 799*8c35d5eeSXin Li 800*8c35d5eeSXin Li<h4 id="s4.8.8-numeric-literals">4.8.8 Numeric Literals</h4> 801*8c35d5eeSXin Li 802*8c35d5eeSXin Li<p><code>long</code>-valued integer literals use an uppercase <code>L</code> suffix, never 803*8c35d5eeSXin Lilowercase (to avoid confusion with the digit <code>1</code>). For example, <code>3000000000L</code> 804*8c35d5eeSXin Lirather than <code class="badcode">3000000000l</code>.</p> 805*8c35d5eeSXin Li 806*8c35d5eeSXin Li<a name="naming"></a> 807*8c35d5eeSXin Li<h2 id="s5-naming">5 Naming</h2> 808*8c35d5eeSXin Li 809*8c35d5eeSXin Li<h3 id="s5.1-identifier-names">5.1 Rules common to all identifiers</h3> 810*8c35d5eeSXin Li 811*8c35d5eeSXin Li<p>Identifiers use only ASCII letters and digits, and, in a small number of cases noted below, 812*8c35d5eeSXin Liunderscores. Thus each valid identifier name is matched by the regular expression 813*8c35d5eeSXin Li<code>\w+</code> .</p> 814*8c35d5eeSXin Li 815*8c35d5eeSXin Li<p>In Google Style, special prefixes or suffixes are <strong>not</strong> used. For example, these 816*8c35d5eeSXin Linames are not Google Style: <code class="badcode">name_</code>, <code class="badcode">mName</code>, 817*8c35d5eeSXin Li<code class="badcode">s_name</code> and <code class="badcode">kName</code>.</p> 818*8c35d5eeSXin Li 819*8c35d5eeSXin Li<h3 id="s5.2-specific-identifier-names">5.2 Rules by identifier type</h3> 820*8c35d5eeSXin Li 821*8c35d5eeSXin Li<h4 id="s5.2.1-package-names">5.2.1 Package names</h4> 822*8c35d5eeSXin Li 823*8c35d5eeSXin Li<p>Package names are all lowercase, with consecutive words simply concatenated together (no 824*8c35d5eeSXin Liunderscores). For example, <code>com.example.deepspace</code>, not 825*8c35d5eeSXin Li<code class="badcode">com.example.deepSpace</code> or 826*8c35d5eeSXin Li<code class="badcode">com.example.deep_space</code>.</p> 827*8c35d5eeSXin Li 828*8c35d5eeSXin Li<h4 id="s5.2.2-class-names">5.2.2 Class names</h4> 829*8c35d5eeSXin Li 830*8c35d5eeSXin Li<p>Class names are written in <a href="#s5.3-camel-case">UpperCamelCase</a>.</p> 831*8c35d5eeSXin Li 832*8c35d5eeSXin Li<p>Class names are typically nouns or noun phrases. For example, 833*8c35d5eeSXin Li<code class="prettyprint lang-java">Character</code> or 834*8c35d5eeSXin Li<code class="prettyprint lang-java">ImmutableList</code>. Interface names may also be nouns or 835*8c35d5eeSXin Linoun phrases (for example, <code class="prettyprint lang-java">List</code>), but may sometimes be 836*8c35d5eeSXin Liadjectives or adjective phrases instead (for example, 837*8c35d5eeSXin Li<code class="prettyprint lang-java">Readable</code>).</p> 838*8c35d5eeSXin Li 839*8c35d5eeSXin Li<p>There are no specific rules or even well-established conventions for naming annotation types.</p> 840*8c35d5eeSXin Li 841*8c35d5eeSXin Li<p><em>Test</em> classes are named starting with the name of the class they are testing, and ending 842*8c35d5eeSXin Liwith <code class="prettyprint lang-java">Test</code>. For example, 843*8c35d5eeSXin Li<code class="prettyprint lang-java">HashTest</code> or 844*8c35d5eeSXin Li<code class="prettyprint lang-java">HashIntegrationTest</code>.</p> 845*8c35d5eeSXin Li 846*8c35d5eeSXin Li<h4 id="s5.2.3-method-names">5.2.3 Method names</h4> 847*8c35d5eeSXin Li 848*8c35d5eeSXin Li<p>Method names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p> 849*8c35d5eeSXin Li 850*8c35d5eeSXin Li<p>Method names are typically verbs or verb phrases. For example, 851*8c35d5eeSXin Li<code class="prettyprint lang-java">sendMessage</code> or 852*8c35d5eeSXin Li<code class="prettyprint lang-java">stop</code>.</p> 853*8c35d5eeSXin Li 854*8c35d5eeSXin Li<p>Underscores may appear in JUnit <em>test</em> method names to separate logical components of the 855*8c35d5eeSXin Liname, with <em>each</em> component written in <a href="#s5.3-camel-case">lowerCamelCase</a>. 856*8c35d5eeSXin LiOne typical pattern is <code><i><methodUnderTest></i>_<i><state></i></code>, 857*8c35d5eeSXin Lifor example <code class="prettyprint lang-java">pop_emptyStack</code>. There is no One Correct 858*8c35d5eeSXin LiWay to name test methods.</p> 859*8c35d5eeSXin Li 860*8c35d5eeSXin Li<a name="constants"></a> 861*8c35d5eeSXin Li<h4 id="s5.2.4-constant-names">5.2.4 Constant names</h4> 862*8c35d5eeSXin Li 863*8c35d5eeSXin Li<p>Constant names use <code class="prettyprint lang-java">CONSTANT_CASE</code>: all uppercase 864*8c35d5eeSXin Liletters, with each word separated from the next by a single underscore. But what <em>is</em> a 865*8c35d5eeSXin Liconstant, exactly?</p> 866*8c35d5eeSXin Li 867*8c35d5eeSXin Li<p>Constants are static final fields whose contents are deeply immutable and whose methods have no 868*8c35d5eeSXin Lidetectable side effects. This includes primitives, Strings, immutable types, and immutable 869*8c35d5eeSXin Licollections of immutable types. If any of the instance's observable state can change, it is not a 870*8c35d5eeSXin Liconstant. Merely <em>intending</em> to never mutate the object is not enough. Examples:</p> 871*8c35d5eeSXin Li 872*8c35d5eeSXin Li<pre class="prettyprint lang-java">// Constants 873*8c35d5eeSXin Listatic final int NUMBER = 5; 874*8c35d5eeSXin Listatic final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann"); 875*8c35d5eeSXin Listatic final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32); 876*8c35d5eeSXin Listatic final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable 877*8c35d5eeSXin Listatic final SomeMutableType[] EMPTY_ARRAY = {}; 878*8c35d5eeSXin Lienum SomeEnum { ENUM_CONSTANT } 879*8c35d5eeSXin Li 880*8c35d5eeSXin Li// Not constants 881*8c35d5eeSXin Listatic String nonFinal = "non-final"; 882*8c35d5eeSXin Lifinal String nonStatic = "non-static"; 883*8c35d5eeSXin Listatic final Set<String> mutableCollection = new HashSet<String>(); 884*8c35d5eeSXin Listatic final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable); 885*8c35d5eeSXin Listatic final ImmutableMap<String, SomeMutableType> mutableValues = 886*8c35d5eeSXin Li ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2); 887*8c35d5eeSXin Listatic final Logger logger = Logger.getLogger(MyClass.getName()); 888*8c35d5eeSXin Listatic final String[] nonEmptyArray = {"these", "can", "change"}; 889*8c35d5eeSXin Li</pre> 890*8c35d5eeSXin Li 891*8c35d5eeSXin Li<p>These names are typically nouns or noun phrases.</p> 892*8c35d5eeSXin Li 893*8c35d5eeSXin Li<h4 id="s5.2.5-non-constant-field-names">5.2.5 Non-constant field names</h4> 894*8c35d5eeSXin Li 895*8c35d5eeSXin Li<p>Non-constant field names (static or otherwise) are written 896*8c35d5eeSXin Liin <a href="#s5.3-camel-case">lowerCamelCase</a>.</p> 897*8c35d5eeSXin Li 898*8c35d5eeSXin Li<p>These names are typically nouns or noun phrases. For example, 899*8c35d5eeSXin Li<code class="prettyprint lang-java">computedValues</code> or 900*8c35d5eeSXin Li<code class="prettyprint lang-java">index</code>.</p> 901*8c35d5eeSXin Li 902*8c35d5eeSXin Li<h4 id="s5.2.6-parameter-names">5.2.6 Parameter names</h4> 903*8c35d5eeSXin Li 904*8c35d5eeSXin Li<p>Parameter names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p> 905*8c35d5eeSXin Li 906*8c35d5eeSXin Li<p>One-character parameter names in public methods should be avoided.</p> 907*8c35d5eeSXin Li 908*8c35d5eeSXin Li<h4 id="s5.2.7-local-variable-names">5.2.7 Local variable names</h4> 909*8c35d5eeSXin Li 910*8c35d5eeSXin Li<p>Local variable names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p> 911*8c35d5eeSXin Li 912*8c35d5eeSXin Li<p>Even when final and immutable, local variables are not considered to be constants, and should not 913*8c35d5eeSXin Libe styled as constants.</p> 914*8c35d5eeSXin Li 915*8c35d5eeSXin Li<h4 id="s5.2.8-type-variable-names">5.2.8 Type variable names</h4> 916*8c35d5eeSXin Li 917*8c35d5eeSXin Li<p>Each type variable is named in one of two styles:</p> 918*8c35d5eeSXin Li 919*8c35d5eeSXin Li<ul> 920*8c35d5eeSXin Li <li>A single capital letter, optionally followed by a single numeral (such as 921*8c35d5eeSXin Li <code class="prettyprint lang-java">E</code>, <code class="prettyprint lang-java">T</code>, 922*8c35d5eeSXin Li <code class="prettyprint lang-java">X</code>, <code class="prettyprint lang-java">T2</code>) 923*8c35d5eeSXin Li </li> 924*8c35d5eeSXin Li 925*8c35d5eeSXin Li <li>A name in the form used for classes (see Section 5.2.2, 926*8c35d5eeSXin Li <a href="#s5.2.2-class-names">Class names</a>), followed by the capital letter 927*8c35d5eeSXin Li <code class="prettyprint lang-java">T</code> (examples: 928*8c35d5eeSXin Li <code class="prettyprint lang-java">RequestT</code>, 929*8c35d5eeSXin Li <code class="prettyprint lang-java">FooBarT</code>).</li> 930*8c35d5eeSXin Li</ul> 931*8c35d5eeSXin Li 932*8c35d5eeSXin Li<a name="acronyms"></a> 933*8c35d5eeSXin Li<a name="camelcase"></a> 934*8c35d5eeSXin Li<h3 id="s5.3-camel-case">5.3 Camel case: defined</h3> 935*8c35d5eeSXin Li 936*8c35d5eeSXin Li<p>Sometimes there is more than one reasonable way to convert an English phrase into camel case, 937*8c35d5eeSXin Lisuch as when acronyms or unusual constructs like "IPv6" or "iOS" are present. To improve 938*8c35d5eeSXin Lipredictability, Google Style specifies the following (nearly) deterministic scheme.</p> 939*8c35d5eeSXin Li 940*8c35d5eeSXin Li<p>Beginning with the prose form of the name:</p> 941*8c35d5eeSXin Li 942*8c35d5eeSXin Li<ol> 943*8c35d5eeSXin Li <li>Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's 944*8c35d5eeSXin Li algorithm" might become "Muellers algorithm".</li> 945*8c35d5eeSXin Li 946*8c35d5eeSXin Li <li>Divide this result into words, splitting on spaces and any remaining punctuation (typically 947*8c35d5eeSXin Li hyphens). 948*8c35d5eeSXin Li 949*8c35d5eeSXin Li <ul> 950*8c35d5eeSXin Li <li><em>Recommended:</em> if any word already has a conventional camel-case appearance in common 951*8c35d5eeSXin Li usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note 952*8c35d5eeSXin Li that a word such as "iOS" is not really in camel case <em>per se</em>; it defies <em>any</em> 953*8c35d5eeSXin Li convention, so this recommendation does not apply.</li> 954*8c35d5eeSXin Li </ul> 955*8c35d5eeSXin Li </li> 956*8c35d5eeSXin Li 957*8c35d5eeSXin Li <li>Now lowercase <em>everything</em> (including acronyms), then uppercase only the first 958*8c35d5eeSXin Li character of: 959*8c35d5eeSXin Li <ul> 960*8c35d5eeSXin Li <li>... each word, to yield <em>upper camel case</em>, or</li> 961*8c35d5eeSXin Li <li>... each word except the first, to yield <em>lower camel case</em></li> 962*8c35d5eeSXin Li </ul> 963*8c35d5eeSXin Li </li> 964*8c35d5eeSXin Li 965*8c35d5eeSXin Li <li>Finally, join all the words into a single identifier.</li> 966*8c35d5eeSXin Li</ol> 967*8c35d5eeSXin Li 968*8c35d5eeSXin Li<p>Note that the casing of the original words is almost entirely disregarded. Examples:</p> 969*8c35d5eeSXin Li 970*8c35d5eeSXin Li<table> 971*8c35d5eeSXin Li <tbody><tr> 972*8c35d5eeSXin Li <th>Prose form</th> 973*8c35d5eeSXin Li <th>Correct</th> 974*8c35d5eeSXin Li <th>Incorrect</th> 975*8c35d5eeSXin Li </tr> 976*8c35d5eeSXin Li <tr> 977*8c35d5eeSXin Li <td>"XML HTTP request"</td> 978*8c35d5eeSXin Li <td><code class="prettyprint lang-java">XmlHttpRequest</code></td> 979*8c35d5eeSXin Li <td><code class="badcode">XMLHTTPRequest</code></td> 980*8c35d5eeSXin Li </tr> 981*8c35d5eeSXin Li <tr> 982*8c35d5eeSXin Li <td>"new customer ID"</td> 983*8c35d5eeSXin Li <td><code class="prettyprint lang-java">newCustomerId</code></td> 984*8c35d5eeSXin Li <td><code class="badcode">newCustomerID</code></td> 985*8c35d5eeSXin Li </tr> 986*8c35d5eeSXin Li <tr> 987*8c35d5eeSXin Li <td>"inner stopwatch"</td> 988*8c35d5eeSXin Li <td><code class="prettyprint lang-java">innerStopwatch</code></td> 989*8c35d5eeSXin Li <td><code class="badcode">innerStopWatch</code></td> 990*8c35d5eeSXin Li </tr> 991*8c35d5eeSXin Li <tr> 992*8c35d5eeSXin Li <td>"supports IPv6 on iOS?"</td> 993*8c35d5eeSXin Li <td><code class="prettyprint lang-java">supportsIpv6OnIos</code></td> 994*8c35d5eeSXin Li <td><code class="badcode">supportsIPv6OnIOS</code></td> 995*8c35d5eeSXin Li </tr> 996*8c35d5eeSXin Li <tr> 997*8c35d5eeSXin Li <td>"YouTube importer"</td> 998*8c35d5eeSXin Li <td><code class="prettyprint lang-java">YouTubeImporter</code><br> 999*8c35d5eeSXin Li <code class="prettyprint lang-java">YoutubeImporter</code>*</td> 1000*8c35d5eeSXin Li <td></td> 1001*8c35d5eeSXin Li </tr> 1002*8c35d5eeSXin Li</tbody></table> 1003*8c35d5eeSXin Li 1004*8c35d5eeSXin Li<p>*Acceptable, but not recommended.</p> 1005*8c35d5eeSXin Li 1006*8c35d5eeSXin Li<p class="note"><strong>Note:</strong> Some words are ambiguously hyphenated in the English 1007*8c35d5eeSXin Lilanguage: for example "nonempty" and "non-empty" are both correct, so the method names 1008*8c35d5eeSXin Li<code class="prettyprint lang-java">checkNonempty</code> and 1009*8c35d5eeSXin Li<code class="prettyprint lang-java">checkNonEmpty</code> are likewise both correct.</p> 1010*8c35d5eeSXin Li 1011*8c35d5eeSXin Li 1012*8c35d5eeSXin Li<h2 id="s6-programming-practices">6 Programming Practices</h2> 1013*8c35d5eeSXin Li 1014*8c35d5eeSXin Li<h3 id="s6.1-override-annotation">6.1 <code>@Override</code>: always used</h3> 1015*8c35d5eeSXin Li 1016*8c35d5eeSXin Li<p>A method is marked with the <code class="prettyprint lang-java">@Override</code> annotation 1017*8c35d5eeSXin Liwhenever it is legal. This includes a class method overriding a superclass method, a class method 1018*8c35d5eeSXin Liimplementing an interface method, and an interface method respecifying a superinterface 1019*8c35d5eeSXin Limethod.</p> 1020*8c35d5eeSXin Li 1021*8c35d5eeSXin Li<p class="exception"><strong>Exception:</strong> 1022*8c35d5eeSXin Li<code class="prettyprint lang-java">@Override</code> may be omitted when the parent method is 1023*8c35d5eeSXin Li<code class="prettyprint lang-java">@Deprecated</code>.</p> 1024*8c35d5eeSXin Li 1025*8c35d5eeSXin Li<a name="caughtexceptions"></a> 1026*8c35d5eeSXin Li<h3 id="s6.2-caught-exceptions">6.2 Caught exceptions: not ignored</h3> 1027*8c35d5eeSXin Li 1028*8c35d5eeSXin Li<p>Except as noted below, it is very rarely correct to do nothing in response to a caught 1029*8c35d5eeSXin Liexception. (Typical responses are to log it, or if it is considered "impossible", rethrow it as an 1030*8c35d5eeSXin Li<code class="prettyprint lang-java">AssertionError</code>.)</p> 1031*8c35d5eeSXin Li 1032*8c35d5eeSXin Li<p>When it truly is appropriate to take no action whatsoever in a catch block, the reason this is 1033*8c35d5eeSXin Lijustified is explained in a comment.</p> 1034*8c35d5eeSXin Li 1035*8c35d5eeSXin Li<pre class="prettyprint lang-java">try { 1036*8c35d5eeSXin Li int i = Integer.parseInt(response); 1037*8c35d5eeSXin Li return handleNumericResponse(i); 1038*8c35d5eeSXin Li} catch (NumberFormatException ok) { 1039*8c35d5eeSXin Li // it's not numeric; that's fine, just continue 1040*8c35d5eeSXin Li} 1041*8c35d5eeSXin Lireturn handleTextResponse(response); 1042*8c35d5eeSXin Li</pre> 1043*8c35d5eeSXin Li 1044*8c35d5eeSXin Li<p class="exception"><strong>Exception:</strong> In tests, a caught exception may be ignored 1045*8c35d5eeSXin Liwithout comment <em>if</em> its name is or begins with <code class="prettyprint lang-java">expected</code>. The 1046*8c35d5eeSXin Lifollowing is a very common idiom for ensuring that the code under test <em>does</em> throw an 1047*8c35d5eeSXin Liexception of the expected type, so a comment is unnecessary here.</p> 1048*8c35d5eeSXin Li 1049*8c35d5eeSXin Li<pre class="prettyprint lang-java">try { 1050*8c35d5eeSXin Li emptyStack.pop(); 1051*8c35d5eeSXin Li fail(); 1052*8c35d5eeSXin Li} catch (NoSuchElementException expected) { 1053*8c35d5eeSXin Li} 1054*8c35d5eeSXin Li</pre> 1055*8c35d5eeSXin Li 1056*8c35d5eeSXin Li<h3 id="s6.3-static-members">6.3 Static members: qualified using class</h3> 1057*8c35d5eeSXin Li 1058*8c35d5eeSXin Li<p>When a reference to a static class member must be qualified, it is qualified with that class's 1059*8c35d5eeSXin Liname, not with a reference or expression of that class's type.</p> 1060*8c35d5eeSXin Li 1061*8c35d5eeSXin Li<pre class="prettyprint lang-java">Foo aFoo = ...; 1062*8c35d5eeSXin LiFoo.aStaticMethod(); // good 1063*8c35d5eeSXin Li<span class="badcode">aFoo.aStaticMethod();</span> // bad 1064*8c35d5eeSXin Li<span class="badcode">somethingThatYieldsAFoo().aStaticMethod();</span> // very bad 1065*8c35d5eeSXin Li</pre> 1066*8c35d5eeSXin Li 1067*8c35d5eeSXin Li<a name="finalizers"></a> 1068*8c35d5eeSXin Li<h3 id="s6.4-finalizers">6.4 Finalizers: not used</h3> 1069*8c35d5eeSXin Li 1070*8c35d5eeSXin Li<p>It is <strong>extremely rare</strong> to override <code class="prettyprint 1071*8c35d5eeSXin Lilang-java">Object.finalize</code>.</p> 1072*8c35d5eeSXin Li 1073*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> Don't do it. If you absolutely must, first read and understand 1074*8c35d5eeSXin Li 1075*8c35d5eeSXin Li 1076*8c35d5eeSXin Li <a href="http://books.google.com/books?isbn=8131726592"><em>Effective Java</em> Item 7,</a> 1077*8c35d5eeSXin Li 1078*8c35d5eeSXin Li"Avoid Finalizers," very carefully, and <em>then</em> don't do it.</p> 1079*8c35d5eeSXin Li 1080*8c35d5eeSXin Li 1081*8c35d5eeSXin Li<a name="javadoc"></a> 1082*8c35d5eeSXin Li<h2 id="s7-javadoc">7 Javadoc</h2> 1083*8c35d5eeSXin Li 1084*8c35d5eeSXin Li 1085*8c35d5eeSXin Li 1086*8c35d5eeSXin Li<h3 id="s7.1-javadoc-formatting">7.1 Formatting</h3> 1087*8c35d5eeSXin Li 1088*8c35d5eeSXin Li<h4 id="s7.1.1-javadoc-multi-line">7.1.1 General form</h4> 1089*8c35d5eeSXin Li 1090*8c35d5eeSXin Li<p>The <em>basic</em> formatting of Javadoc blocks is as seen in this example:</p> 1091*8c35d5eeSXin Li 1092*8c35d5eeSXin Li<pre class="prettyprint lang-java">/** 1093*8c35d5eeSXin Li * Multiple lines of Javadoc text are written here, 1094*8c35d5eeSXin Li * wrapped normally... 1095*8c35d5eeSXin Li */ 1096*8c35d5eeSXin Lipublic int method(String p1) { ... } 1097*8c35d5eeSXin Li</pre> 1098*8c35d5eeSXin Li 1099*8c35d5eeSXin Li<p>... or in this single-line example:</p> 1100*8c35d5eeSXin Li 1101*8c35d5eeSXin Li<pre class="prettyprint lang-java">/** An especially short bit of Javadoc. */ 1102*8c35d5eeSXin Li</pre> 1103*8c35d5eeSXin Li 1104*8c35d5eeSXin Li<p>The basic form is always acceptable. The single-line form may be substituted when the entirety 1105*8c35d5eeSXin Liof the Javadoc block (including comment markers) can fit on a single line. Note that this only 1106*8c35d5eeSXin Liapplies when there are no block tags such as <code>@return</code>. 1107*8c35d5eeSXin Li 1108*8c35d5eeSXin Li</p><h4 id="s7.1.2-javadoc-paragraphs">7.1.2 Paragraphs</h4> 1109*8c35d5eeSXin Li 1110*8c35d5eeSXin Li<p>One blank line—that is, a line containing only the aligned leading asterisk 1111*8c35d5eeSXin Li(<code>*</code>)—appears between paragraphs, and before the group of block tags if 1112*8c35d5eeSXin Lipresent. Each paragraph but the first has <code><p></code> immediately before the first word, 1113*8c35d5eeSXin Liwith no space after.</p> 1114*8c35d5eeSXin Li 1115*8c35d5eeSXin Li<a name="s7.1.3-javadoc-at-clauses"></a> 1116*8c35d5eeSXin Li 1117*8c35d5eeSXin Li<h4 id="s7.1.3-javadoc-block-tags">7.1.3 Block tags</h4> 1118*8c35d5eeSXin Li 1119*8c35d5eeSXin Li<p>Any of the standard "block tags" that are used appear in the order <code>@param</code>, 1120*8c35d5eeSXin Li<code>@return</code>, <code>@throws</code>, <code>@deprecated</code>, and these four types never 1121*8c35d5eeSXin Liappear with an empty description. When a block tag doesn't fit on a single line, continuation lines 1122*8c35d5eeSXin Liare indented four (or more) spaces from the position of the <code>@</code>. 1123*8c35d5eeSXin Li</p> 1124*8c35d5eeSXin Li 1125*8c35d5eeSXin Li<h3 id="s7.2-summary-fragment">7.2 The summary fragment</h3> 1126*8c35d5eeSXin Li 1127*8c35d5eeSXin Li<p>Each Javadoc block begins with a brief <strong>summary fragment</strong>. This 1128*8c35d5eeSXin Lifragment is very important: it is the only part of the text that appears in certain contexts such as 1129*8c35d5eeSXin Liclass and method indexes.</p> 1130*8c35d5eeSXin Li 1131*8c35d5eeSXin Li<p>This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does 1132*8c35d5eeSXin Li<strong>not</strong> begin with <code class="badcode">A {@code Foo} is a...</code>, or 1133*8c35d5eeSXin Li<code class="badcode">This method returns...</code>, nor does it form a complete imperative sentence 1134*8c35d5eeSXin Lilike <code class="badcode">Save the record.</code>. However, the fragment is capitalized and 1135*8c35d5eeSXin Lipunctuated as if it were a complete sentence.</p> 1136*8c35d5eeSXin Li 1137*8c35d5eeSXin Li<p class="tip"><strong>Tip:</strong> A common mistake is to write simple Javadoc in the form 1138*8c35d5eeSXin Li<code class="badcode">/** @return the customer ID */</code>. This is incorrect, and should be 1139*8c35d5eeSXin Lichanged to <code class="prettyprint lang-java">/** Returns the customer ID. */</code>.</p> 1140*8c35d5eeSXin Li 1141*8c35d5eeSXin Li<a name="s7.3.3-javadoc-optional"></a> 1142*8c35d5eeSXin Li<h3 id="s7.3-javadoc-where-required">7.3 Where Javadoc is used</h3> 1143*8c35d5eeSXin Li 1144*8c35d5eeSXin Li<p>At the <em>minimum</em>, Javadoc is present for every 1145*8c35d5eeSXin Li<code class="prettyprint lang-java">public</code> class, and every 1146*8c35d5eeSXin Li<code class="prettyprint lang-java">public</code> or 1147*8c35d5eeSXin Li<code class="prettyprint lang-java">protected</code> member of such a class, with a few exceptions 1148*8c35d5eeSXin Linoted below.</p> 1149*8c35d5eeSXin Li 1150*8c35d5eeSXin Li<p>Additional Javadoc content may also be present, as explained in Section 7.3.4, 1151*8c35d5eeSXin Li<a href="#s7.3.4-javadoc-non-required">Non-required Javadoc</a>.</p> 1152*8c35d5eeSXin Li 1153*8c35d5eeSXin Li<h4 id="s7.3.1-javadoc-exception-self-explanatory">7.3.1 Exception: self-explanatory methods</h4> 1154*8c35d5eeSXin Li 1155*8c35d5eeSXin Li<p>Javadoc is optional for "simple, obvious" methods like 1156*8c35d5eeSXin Li<code class="prettyprint lang-java">getFoo</code>, in cases where there <em>really and truly</em> is 1157*8c35d5eeSXin Linothing else worthwhile to say but "Returns the foo".</p> 1158*8c35d5eeSXin Li 1159*8c35d5eeSXin Li<p class="note"><strong>Important:</strong> it is not appropriate to cite this exception to justify 1160*8c35d5eeSXin Liomitting relevant information that a typical reader might need to know. For example, for a method 1161*8c35d5eeSXin Linamed <code class="prettyprint lang-java">getCanonicalName</code>, don't omit its documentation 1162*8c35d5eeSXin Li(with the rationale that it would say only 1163*8c35d5eeSXin Li<code class="badcode">/** Returns the canonical name. */</code>) if a typical reader may have no idea 1164*8c35d5eeSXin Liwhat the term "canonical name" means!</p> 1165*8c35d5eeSXin Li 1166*8c35d5eeSXin Li<h4 id="s7.3.2-javadoc-exception-overrides">7.3.2 Exception: overrides</h4> 1167*8c35d5eeSXin Li 1168*8c35d5eeSXin Li<p>Javadoc is not always present on a method that overrides a supertype method. 1169*8c35d5eeSXin Li 1170*8c35d5eeSXin Li</p> 1171*8c35d5eeSXin Li 1172*8c35d5eeSXin Li 1173*8c35d5eeSXin Li 1174*8c35d5eeSXin Li<h4 id="s7.3.4-javadoc-non-required">7.3.4 Non-required Javadoc</h4> 1175*8c35d5eeSXin Li 1176*8c35d5eeSXin Li<p>Other classes and members have Javadoc <em>as needed or desired</em>. 1177*8c35d5eeSXin Li 1178*8c35d5eeSXin Li</p><p>Whenever an implementation comment would be used to define the overall purpose or behavior of a 1179*8c35d5eeSXin Liclass or member, that comment is written as Javadoc instead (using <code>/**</code>).</p> 1180*8c35d5eeSXin Li 1181*8c35d5eeSXin Li<p>Non-required Javadoc is not strictly required to follow the formatting rules of Sections 1182*8c35d5eeSXin Li7.1.2, 7.1.3, and 7.2, though it is of course recommended.</p> 1183*8c35d5eeSXin Li 1184*8c35d5eeSXin Li 1185*8c35d5eeSXin Li 1186*8c35d5eeSXin Li</div> 1187*8c35d5eeSXin Li</div> 1188*8c35d5eeSXin Li</body> 1189*8c35d5eeSXin Li</html> 1190