Home | History | Annotate | Download | only in source
      1 <html devsite>
      2   <head>
      3     <title>Code Style for Contributors</title>
      4     <meta name="project_path" value="/_project.yaml" />
      5     <meta name="book_path" value="/_book.yaml" />
      6   </head>
      7   <body>
      8   <!--
      9       Copyright 2017 The Android Open Source Project
     10 
     11       Licensed under the Apache License, Version 2.0 (the "License");
     12       you may not use this file except in compliance with the License.
     13       You may obtain a copy of the License at
     14 
     15           http://www.apache.org/licenses/LICENSE-2.0
     16 
     17       Unless required by applicable law or agreed to in writing, software
     18       distributed under the License is distributed on an "AS IS" BASIS,
     19       WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     20       See the License for the specific language governing permissions and
     21       limitations under the License.
     22   -->
     23 
     24 
     25 
     26 <p>The code styles below are strict rules for contributing Java code to the
     27 Android Open Source Project (AOSP).  Contributions to the Android platform that
     28 do not adhere to these rules are generally <em>not accepted</em>. We recognize
     29 that not all existing code follows these rules, but we expect all new code to
     30 be compliant.</p>
     31 
     32 <p class="note"><strong>Note:</strong> These rules are intended for the Android
     33 platform and are not required of Android app developers. App developers may
     34 follow the standard of their choosing, such as the <a
     35 href="https://google.github.io/styleguide/javaguide.html">Google Java Style
     36 Guide</a>.</p>
     37 
     38 <h2 id="java-language-rules">Java Language Rules</h2>
     39 <p>Android follows standard Java coding conventions with the additional rules
     40 described below.</p>
     41 
     42 <h3 id="dont-ignore-exceptions">Don't Ignore Exceptions</h3>
     43 <p>It can be tempting to write code that completely ignores an exception, such
     44 as:</p>
     45 <pre><code>void setServerPort(String value) {
     46     try {
     47         serverPort = Integer.parseInt(value);
     48     } catch (NumberFormatException e) { }
     49 }
     50 </code></pre>
     51 <p>Do not do this. While you may think your code will never encounter this error
     52 condition or that it is not important to handle it, ignoring exceptions as above
     53 creates mines in your code for someone else to trigger some day. You must handle
     54 every Exception in your code in a principled way; the specific handling varies
     55 depending on the case.</p>
     56 <p><em>Anytime somebody has an empty catch clause they should have a
     57 creepy feeling. There are definitely times when it is actually the correct
     58 thing to do, but at least you have to think about it. In Java you can't escape
     59 the creepy feeling.</em> -<a href="http://www.artima.com/intv/solid4.html">James Gosling</a></p>
     60 <p>Acceptable alternatives (in order of preference) are:</p>
     61 <ul>
     62 <li>Throw the exception up to the caller of your method.
     63 <pre><code>void setServerPort(String value) throws NumberFormatException {
     64     serverPort = Integer.parseInt(value);
     65 }
     66 </code></pre>
     67 </li>
     68 <li>Throw a new exception that's appropriate to your level of abstraction.
     69 <pre><code>void setServerPort(String value) throws ConfigurationException {
     70     try {
     71         serverPort = Integer.parseInt(value);
     72     } catch (NumberFormatException e) {
     73         throw new ConfigurationException("Port " + value + " is not valid.");
     74     }
     75 }
     76 </code></pre>
     77 </li>
     78 <li>Handle the error gracefully and substitute an appropriate value in the
     79 catch {} block.
     80 <pre><code>/** Set port. If value is not a valid number, 80 is substituted. */
     81 
     82 void setServerPort(String value) {
     83     try {
     84         serverPort = Integer.parseInt(value);
     85     } catch (NumberFormatException e) {
     86         serverPort = 80;  // default port for server
     87     }
     88 }
     89 </code></pre>
     90 </li>
     91 <li>Catch the Exception and throw a new <code>RuntimeException</code>. This is
     92 dangerous, so do it only if you are positive that if this error occurs the
     93 appropriate thing to do is crash.
     94 <pre><code>/** Set port. If value is not a valid number, die. */
     95 
     96 void setServerPort(String value) {
     97     try {
     98         serverPort = Integer.parseInt(value);
     99     } catch (NumberFormatException e) {
    100         throw new RuntimeException("port " + value " is invalid, ", e);
    101     }
    102 }
    103 </code></pre>
    104 <p class="note"><strong>Note</strong> The original exception is passed to the
    105 constructor for RuntimeException. If your code must compile under Java 1.3, you
    106 must omit the exception that is the cause.</p>
    107 </li>
    108 <li>As a last resort, if you are confident that ignoring the exception is
    109 appropriate then you may ignore it, but you must also comment why with a good
    110 reason:
    111 <pre><code>/** If value is not a valid number, original port number is used. */
    112 void setServerPort(String value) {
    113     try {
    114         serverPort = Integer.parseInt(value);
    115     } catch (NumberFormatException e) {
    116         // Method is documented to just ignore invalid user input.
    117         // serverPort will just be unchanged.
    118     }
    119 }
    120 </code></pre>
    121 </li>
    122 </ul>
    123 
    124 <h3 id="dont-catch-generic-exception">Don't Catch Generic Exception</h3>
    125 <p>It can also be tempting to be lazy when catching exceptions and do
    126 something like this:</p>
    127 <pre><code>try {
    128     someComplicatedIOFunction();        // may throw IOException
    129     someComplicatedParsingFunction();   // may throw ParsingException
    130     someComplicatedSecurityFunction();  // may throw SecurityException
    131     // phew, made it all the way
    132 } catch (Exception e) {                 // I'll just catch all exceptions
    133     handleError();                      // with one generic handler!
    134 }
    135 </code></pre>
    136 <p>Do not do this. In almost all cases it is inappropriate to catch generic
    137 Exception or Throwable (preferably not Throwable because it includes Error
    138 exceptions). It is very dangerous because it means that Exceptions
    139 you never expected (including RuntimeExceptions like ClassCastException) get
    140 caught in application-level error handling. It obscures the failure handling
    141 properties of your code, meaning if someone adds a new type of Exception in the
    142 code you're calling, the compiler won't help you realize you need to handle the
    143 error differently. In most cases you shouldn't be handling different types of
    144 exception the same way.</p>
    145 <p>The rare exception to this rule is test code and top-level code where you
    146 want to catch all kinds of errors (to prevent them from showing up in a UI, or
    147 to keep a batch job running). In these cases you may catch generic Exception
    148 (or Throwable) and handle the error appropriately. Think very carefully before
    149 doing this, though, and put in comments explaining why it is safe in this place.</p>
    150 <p>Alternatives to catching generic Exception:</p>
    151 <ul>
    152 <li>
    153 <p>Catch each exception separately as separate catch blocks after a single
    154 try. This can be awkward but is still preferable to catching all Exceptions.
    155 Beware repeating too much code in the catch blocks.</li></p>
    156 </li>
    157 <li>
    158 <p>Refactor your code to have more fine-grained error handling, with multiple
    159 try blocks. Split up the IO from the parsing, handle errors separately in each
    160 case.</p>
    161 </li>
    162 <li>
    163 <p>Rethrow the exception. Many times you don't need to catch the exception at
    164 this level anyway, just let the method throw it.</p>
    165 </li>
    166 </ul>
    167 <p>Remember: exceptions are your friend! When the compiler complains you're
    168 not catching an exception, don't scowl. Smile: the compiler just made it
    169 easier for you to catch runtime problems in your code.</p>
    170 <h3 id="dont-use-finalizers">Don't Use Finalizers</h3>
    171 <p>Finalizers are a way to have a chunk of code executed when an object is
    172 garbage collected. While they can be handy for doing cleanup (particularly of
    173 external resources), there are no guarantees as to when a finalizer will be
    174 called (or even that it will be called at all).</p>
    175 <p>Android doesn't use finalizers. In most cases, you can do what
    176 you need from a finalizer with good exception handling. If you absolutely need
    177 it, define a close() method (or the like) and document exactly when that
    178 method needs to be called (see InputStream for an example). In this case it is
    179 appropriate but not required to print a short log message from the finalizer,
    180 as long as it is not expected to flood the logs.</p>
    181 
    182 <h3 id="fully-qualify-imports">Fully Qualify Imports</h3>
    183 <p>When you want to use class Bar from package foo,there
    184 are two possible ways to import it:</p>
    185 <ul>
    186 <li><code>import foo.*;</code>
    187 <p>Potentially reduces the number of import statements.</p></li>
    188 <li><code>import foo.Bar;</code>
    189 <p>Makes it obvious what classes are actually used and the code is more readable
    190 for maintainers.</p></li></ul>
    191 <p>Use <code>import foo.Bar;</code> for importing all Android code. An explicit
    192 exception is made for java standard libraries (<code>java.util.*</code>,
    193 <code>java.io.*</code>, etc.) and unit test code
    194 (<code>junit.framework.*</code>).</p>
    195 
    196 <h2 id="java-library-rules">Java Library Rules</h2>
    197 <p>There are conventions for using Android's Java libraries and tools. In some
    198 cases, the convention has changed in important ways and older code might use a
    199 deprecated pattern or library. When working with such code, it's okay to
    200 continue the existing style. When creating new components however, never use
    201 deprecated libraries.</p>
    202 
    203 <h2 id="java-style-rules">Java Style Rules</h2>
    204 
    205 <h3 id="use-javadoc-standard-comments">Use Javadoc Standard Comments</h3>
    206 <p>Every file should have a copyright statement at the top, followed by package
    207 and import statements (each block separated by a blank line) and finally the
    208 class or interface declaration. In the Javadoc comments, describe what the class
    209 or interface does.</p>
    210 <pre><code>/*
    211  * Copyright (C) 2015 The Android Open Source Project
    212  *
    213  * Licensed under the Apache License, Version 2.0 (the "License");
    214  * you may not use this file except in compliance with the License.
    215  * You may obtain a copy of the License at
    216  *
    217  *      http://www.apache.org/licenses/LICENSE-2.0
    218  *
    219  * Unless required by applicable law or agreed to in writing, software
    220  * distributed under the License is distributed on an "AS IS" BASIS,
    221  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    222  * See the License for the specific language governing permissions and
    223  * limitations under the License.
    224  */
    225 
    226 package com.android.internal.foo;
    227 
    228 import android.os.Blah;
    229 import android.view.Yada;
    230 
    231 import java.sql.ResultSet;
    232 import java.sql.SQLException;
    233 
    234 /**
    235  * Does X and Y and provides an abstraction for Z.
    236  */
    237 
    238 public class Foo {
    239     ...
    240 }
    241 </code></pre>
    242 <p>Every class and nontrivial public method you write <em>must</em> contain a
    243 Javadoc comment with at least one sentence describing what the class or method
    244 does. This sentence should start with a third person descriptive verb.</p>
    245 <p>Examples:</p>
    246 <pre><code>/** Returns the correctly rounded positive square root of a double value. */
    247 static double sqrt(double a) {
    248     ...
    249 }
    250 </code></pre>
    251 <p>or</p>
    252 <pre><code>/**
    253  * Constructs a new String by converting the specified array of
    254  * bytes using the platform's default character encoding.
    255  */
    256 public String(byte[] bytes) {
    257     ...
    258 }
    259 </code></pre>
    260 <p>You do not need to write Javadoc for trivial get and set methods such as
    261 <code>setFoo()</code> if all your Javadoc would say is "sets Foo". If the method
    262 does something more complex (such as enforcing a constraint or has an important
    263 side effect), then you must document it. If it's not obvious what the property
    264 "Foo" means, you should document it.
    265 <p>Every method you write, public or otherwise, would benefit from Javadoc.
    266 Public methods are part of an API and therefore require Javadoc. Android does
    267 not currently enforce a specific style for writing Javadoc comments, but you
    268 should follow the instructions <a
    269 href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">How
    270 to Write Doc Comments for the Javadoc Tool</a>.</p>
    271 
    272 <h3 id="write-short-methods">Write Short Methods</h3>
    273 <p>When feasible, keep methods small and focused. We recognize that long methods
    274 are sometimes appropriate, so no hard limit is placed on method length. If a
    275 method exceeds 40 lines or so, think about whether it can be broken up without
    276 harming the structure of the program.</p>
    277 
    278 <h3 id="define-fields-in-standard-places">Define Fields in Standard Places</h3>
    279 <p>Define fields either at the top of the file or immediately before the
    280 methods that use them.</p>
    281 
    282 <h3 id="limit-variable-scope">Limit Variable Scope</h3>
    283 <p>Keep the scope of local variables to a minimum. By doing so, you
    284 increase the readability and maintainability of your code and reduce the
    285 likelihood of error. Each variable should be declared in the innermost block
    286 that encloses all uses of the variable.</p>
    287 <p>Local variables should be declared at the point they are first used. Nearly
    288 every local variable declaration should contain an initializer. If you don't
    289 yet have enough information to initialize a variable sensibly, postpone the
    290 declaration until you do.</p>
    291 <p>The exception is try-catch statements. If a variable is initialized with the
    292 return value of a method that throws a checked exception, it must be initialized
    293 inside a try block. If the value must be used outside of the try block, then it
    294 must be declared before the try block, where it cannot yet be sensibly
    295 initialized:</p>
    296 <pre><code>// Instantiate class cl, which represents some sort of Set
    297 Set s = null;
    298 try {
    299     s = (Set) cl.newInstance();
    300 } catch(IllegalAccessException e) {
    301     throw new IllegalArgumentException(cl + " not accessible");
    302 } catch(InstantiationException e) {
    303     throw new IllegalArgumentException(cl + " not instantiable");
    304 }
    305 
    306 // Exercise the set
    307 s.addAll(Arrays.asList(args));
    308 </code></pre>
    309 <p>However, even this case can be avoided by encapsulating the try-catch block
    310 in a method:</p>
    311 <pre><code>Set createSet(Class cl) {
    312     // Instantiate class cl, which represents some sort of Set
    313     try {
    314         return (Set) cl.newInstance();
    315     } catch(IllegalAccessException e) {
    316         throw new IllegalArgumentException(cl + " not accessible");
    317     } catch(InstantiationException e) {
    318         throw new IllegalArgumentException(cl + " not instantiable");
    319     }
    320 }
    321 
    322 ...
    323 
    324 // Exercise the set
    325 Set s = createSet(cl);
    326 s.addAll(Arrays.asList(args));
    327 </code></pre>
    328 <p>Loop variables should be declared in the for statement itself unless there
    329 is a compelling reason to do otherwise:</p>
    330 <pre><code>for (int i = 0; i < n; i++) {
    331     doSomething(i);
    332 }
    333 </code></pre>
    334 <p>and</p>
    335 <pre><code>for (Iterator i = c.iterator(); i.hasNext(); ) {
    336     doSomethingElse(i.next());
    337 }
    338 </code></pre>
    339 
    340 <h3 id="order-import-statements">Order Import Statements</h3>
    341 <p>The ordering of import statements is:</p>
    342 <ol>
    343 <li>
    344 <p>Android imports</p>
    345 </li>
    346 <li>
    347 <p>Imports from third parties (<code>com</code>, <code>junit</code>,
    348 <code>net</code>, <code>org</code>)</p>
    349 </li>
    350 <li>
    351 <p><code>java</code> and <code>javax</code></p>
    352 </li>
    353 </ol>
    354 <p>To exactly match the IDE settings, the imports should be:</p>
    355 <ul>
    356 <li>
    357 <p>Alphabetical within each grouping, with capital letters before lower case
    358 letters (e.g. Z before a).</p>
    359 </li>
    360 <li>
    361 <p>Separated by a blank line between each major grouping (<code>android</code>,
    362 <code>com</code>, <code>junit</code>, <code>net</code>, <code>org</code>,
    363 <code>java</code>, <code>javax</code>).</p>
    364 </li>
    365 </ul>
    366 <p>Originally, there was no style requirement on the ordering, meaning IDEs were
    367 either always changing the ordering or IDE developers had to disable the
    368 automatic import management features and manually maintain the imports. This was
    369 deemed bad. When java-style was asked, the preferred styles varied wildly and it
    370 came down to Android needing to simply "pick an ordering and be consistent." So
    371 we chose a style, updated the style guide, and made the IDEs obey it. We expect
    372 that as IDE users work on the code, imports in all packages will match this
    373 pattern without extra engineering effort.</p>
    374 <p>This style was chosen such that:</p>
    375 <ul>
    376 <li>
    377 <p>The imports people want to look at first tend to be at the top
    378 (<code>android</code>).</p>
    379 </li>
    380 <li>
    381 <p>The imports people want to look at least tend to be at the bottom
    382 (<code>java</code>).</p>
    383 </li>
    384 <li>
    385 <p>Humans can easily follow the style.</p>
    386 </li>
    387 <li>
    388 <p>IDEs can follow the style.</p>
    389 </li>
    390 </ul>
    391 <p>The use and location of static imports have been mildly controversial
    392 issues. Some people prefer static imports to be interspersed with the
    393 remaining imports, while some prefer them to reside above or below all
    394 other imports. Additionally, we have not yet determined how to make all IDEs use
    395 the same ordering. Since many consider this a low priority issue, just use your
    396 judgement and be consistent.</p>
    397 
    398 <h3 id="use-spaces-for-indentation">Use Spaces for Indentation</h3>
    399 <p>We use four (4) space indents for blocks and never tabs. When in doubt, be
    400 consistent with the surrounding code.</p>
    401 <p>We use eight (8) space indents for line wraps, including function calls and
    402 assignments. For example, this is correct:</p>
    403 <pre><code>Instrument i =
    404         someLongExpression(that, wouldNotFit, on, one, line);
    405 </code></pre>
    406 <p>and this is not correct:</p>
    407 <pre><code>Instrument i =
    408     someLongExpression(that, wouldNotFit, on, one, line);
    409 </code></pre>
    410 
    411 <h3 id="follow-field-naming-conventions">Follow Field Naming Conventions</h3>
    412 <ul>
    413 <li>
    414 <p>Non-public, non-static field names start with m.</p>
    415 </li>
    416 <li>
    417 <p>Static field names start with s.</p>
    418 </li>
    419 <li>
    420 <p>Other fields start with a lower case letter.</p>
    421 </li>
    422 <li>
    423 <p>Public static final fields (constants) are ALL_CAPS_WITH_UNDERSCORES.</p>
    424 </li>
    425 </ul>
    426 <p>For example:</p>
    427 <pre><code>public class MyClass {
    428     public static final int SOME_CONSTANT = 42;
    429     public int publicField;
    430     private static MyClass sSingleton;
    431     int mPackagePrivate;
    432     private int mPrivate;
    433     protected int mProtected;
    434 }
    435 </code></pre>
    436 <h3 id="use-standard-brace-style">Use Standard Brace Style</h3>
    437 <p>Braces do not go on their own line; they go on the same line as the code
    438 before them:</p>
    439 <pre><code>class MyClass {
    440     int func() {
    441         if (something) {
    442             // ...
    443         } else if (somethingElse) {
    444             // ...
    445         } else {
    446             // ...
    447         }
    448     }
    449 }
    450 </code></pre>
    451 <p>We require braces around the statements for a conditional. Exception: If the
    452 entire conditional (the condition and the body) fit on one line, you may (but
    453 are not obligated to) put it all on one line. For example, this is acceptable:</p>
    454 <pre><code>if (condition) {
    455     body();
    456 }
    457 </code></pre>
    458 <p>and this is acceptable:</p>
    459 <pre><code>if (condition) body();
    460 </code></pre>
    461 <p>but this is not acceptable:</p>
    462 <pre><code>if (condition)
    463     body();  // bad!
    464 </code></pre>
    465 
    466 <h3 id="limit-line-length">Limit Line Length</h3>
    467 <p>Each line of text in your code should be at most 100 characters long. While
    468 much discussion has surrounded this rule, the decision remains that 100
    469 characters is the maximum <em>with the following exceptions</em>:</p>
    470 <ul>
    471 <li>If a comment line contains an example command or a literal URL
    472 longer than 100 characters, that line may be longer than 100 characters for
    473 ease of cut and paste.</li>
    474 <li>Import lines can go over the limit because humans rarely see them (this also
    475 simplifies tool writing).</li>
    476 </ul>
    477 
    478 <h3 id="use-standard-java-annotations">Use Standard Java Annotations</h3>
    479 <p>Annotations should precede other modifiers for the same language element.
    480 Simple marker annotations (e.g. @Override) can be listed on the same line with
    481 the language element. If there are multiple annotations, or parameterized
    482 annotations, they should each be listed one-per-line in alphabetical
    483 order.</p>
    484 <p>Android standard practices for the three predefined annotations in Java are:</p>
    485 <ul>
    486 <li><code>@Deprecated</code>: The @Deprecated annotation must be used whenever
    487 the use of the annotated element is discouraged. If you use the @Deprecated
    488 annotation, you must also have a @deprecated Javadoc tag and it should name an
    489 alternate implementation. In addition, remember that a @Deprecated method is
    490 <em>still supposed to work</em>. If you see old code that has a @deprecated
    491 Javadoc tag, please add the @Deprecated annotation.
    492 </li>
    493 <li><code>@Override</code>: The @Override annotation must be used whenever a
    494 method overrides the declaration or implementation from a super-class. For
    495 example, if you use the @inheritdocs Javadoc tag, and derive from a class (not
    496 an interface), you must also annotate that the method @Overrides the parent
    497 class's method.</li>
    498 <li><code>@SuppressWarnings</code>: The @SuppressWarnings annotation should be
    499 used only under circumstances where it is impossible to eliminate a warning. If
    500 a warning passes this "impossible to eliminate" test, the @SuppressWarnings
    501 annotation <em>must</em> be used, so as to ensure that all warnings reflect
    502 actual problems in the code.
    503 <p>When a @SuppressWarnings annotation is necessary, it must be prefixed with
    504 a TODO comment that explains the "impossible to eliminate" condition. This
    505 will normally identify an offending class that has an awkward interface. For
    506 example:</p>
    507 <pre><code>// TODO: The third-party class com.third.useful.Utility.rotate() needs generics
    508 &#64;SuppressWarnings("generic-cast")
    509 List&lt;String&gt; blix = Utility.rotate(blax);
    510 </code></pre>
    511 <p>When a @SuppressWarnings annotation is required, the code should be
    512 refactored to isolate the software elements where the annotation applies.</p>
    513 </li>
    514 </ul>
    515 
    516 <h3 id="treat-acronyms-as-words">Treat Acronyms as Words</h3>
    517 <p>Treat acronyms and abbreviations as words in naming variables, methods, and
    518 classes to make names more readable:</p>
    519 <table>
    520 <thead>
    521 <tr>
    522 <th>Good</th>
    523 <th>Bad</th>
    524 </tr>
    525 </thead>
    526 <tbody>
    527 <tr>
    528 <td>XmlHttpRequest</td>
    529 <td>XMLHTTPRequest</td>
    530 </tr>
    531 <tr>
    532 <td>getCustomerId</td>
    533 <td>getCustomerID</td>
    534 </tr>
    535 <tr>
    536 <td>class Html</td>
    537 <td>class HTML</td>
    538 </tr>
    539 <tr>
    540 <td>String url</td>
    541 <td>String URL</td>
    542 </tr>
    543 <tr>
    544 <td>long id</td>
    545 <td>long ID</td>
    546 </tr>
    547 </tbody>
    548 </table>
    549 <p>As both the JDK and the Android code bases are very inconsistent around
    550 acronyms, it is virtually impossible to be consistent with the surrounding
    551 code. Therefore, always treat acronyms as words.</p>
    552 
    553 <h3 id="use-todo-comments">Use TODO Comments</h3>
    554 <p>Use TODO comments for code that is temporary, a short-term solution, or
    555 good-enough but not perfect. TODOs should include the string TODO in all caps,
    556 followed by a colon:</p>
    557 <pre><code>// TODO: Remove this code after the UrlTable2 has been checked in.
    558 </code></pre>
    559 <p>and</p>
    560 <pre><code>// TODO: Change this to use a flag instead of a constant.
    561 </code></pre>
    562 <p>If your TODO is of the form "At a future date do something" make sure that
    563 you either include a very specific date ("Fix by November 2005") or a very
    564 specific event ("Remove this code after all production mixers understand
    565 protocol V7.").</p>
    566 
    567 <h3 id="log-sparingly">Log Sparingly</h3>
    568 <p>While logging is necessary, it has a significantly negative impact on
    569 performance and quickly loses its usefulness if not kept reasonably
    570 terse. The logging facilities provides five different levels of logging:</p>
    571 <ul>
    572 <li><code>ERROR</code>:
    573 Use when something fatal has happened, i.e. something will have user-visible
    574 consequences and won't be recoverable without explicitly deleting some data,
    575 uninstalling applications, wiping the data partitions or reflashing the entire
    576 device (or worse). This level is always logged. Issues that justify some logging
    577 at the ERROR level are typically good candidates to be reported to a
    578 statistics-gathering server.</li>
    579 <li><code>WARNING</code>:
    580 Use when something serious and unexpected happened, i.e. something that will
    581 have user-visible consequences but is likely to be recoverable without data loss
    582 by performing some explicit action, ranging from waiting or restarting an app
    583 all the way to re-downloading a new version of an application or rebooting the
    584 device. This level is always logged. Issues that justify some logging at the
    585 WARNING level might also be considered for reporting to a statistics-gathering
    586 server.</li>
    587 <li><code>INFORMATIVE:</code>
    588 Use to note that something interesting to most people happened, i.e. when a
    589 situation is detected that is likely to have widespread impact, though isn't
    590 necessarily an error. Such a condition should only be logged by a module that
    591 reasonably believes that it is the most authoritative in that domain (to avoid
    592 duplicate logging by non-authoritative components). This level is always logged.
    593 </li>
    594 <li><code>DEBUG</code>:
    595 Use to further note what is happening on the device that could be relevant to
    596 investigate and debug unexpected behaviors. You should log only what is needed
    597 to gather enough information about what is going on about your component. If
    598 your debug logs are dominating the log then you probably should be using verbose
    599 logging.
    600 <p>This level will be logged, even on release builds, and is required to be
    601 surrounded by an <code>if (LOCAL_LOG)</code> or <code>if (LOCAL_LOGD)</code>
    602 block, where <code>LOCAL_LOG[D]</code> is defined in your class or subcomponent,
    603 so that there can exist a possibility to disable all such logging. There must
    604 therefore be no active logic in an <code>if (LOCAL_LOG)</code> block. All the
    605 string building for the log also needs to be placed inside the <code>if
    606 (LOCAL_LOG)</code> block. The logging call should not be re-factored out into a
    607 method call if it is going to cause the string building to take place outside
    608 of the <code>if (LOCAL_LOG)</code> block.</p>
    609 <p>There is some code that still says <code>if (localLOGV)</code>. This is
    610 considered acceptable as well, although the name is nonstandard.</p>
    611 </li>
    612 <li><code>VERBOSE</code>:
    613 Use for everything else. This level will only be logged on debug builds and
    614 should be surrounded by an <code>if (LOCAL_LOGV)</code> block (or equivalent) so
    615 it can be compiled out by default. Any string building will be stripped out of
    616 release builds and needs to appear inside the <code>if (LOCAL_LOGV)</code> block.
    617 </li>
    618 </ul>
    619 <p><em>Notes:</em> </p>
    620 <ul>
    621 <li>Within a given module, other than at the VERBOSE level, an
    622 error should only be reported once if possible. Within a single chain of
    623 function calls within a module, only the innermost function should return the
    624 error, and callers in the same module should only add some logging if that
    625 significantly helps to isolate the issue.</li>
    626 <li>In a chain of modules, other than at the VERBOSE level, when a
    627 lower-level module detects invalid data coming from a higher-level module, the
    628 lower-level module should only log this situation to the DEBUG log, and only
    629 if logging provides information that is not otherwise available to the caller.
    630 Specifically, there is no need to log situations where an exception is thrown
    631 (the exception should contain all the relevant information), or where the only
    632 information being logged is contained in an error code. This is especially
    633 important in the interaction between the framework and applications, and
    634 conditions caused by third-party applications that are properly handled by the
    635 framework should not trigger logging higher than the DEBUG level. The only
    636 situations that should trigger logging at the INFORMATIVE level or higher is
    637 when a module or application detects an error at its own level or coming from
    638 a lower level.</li>
    639 <li>When a condition that would normally justify some logging is
    640 likely to occur many times, it can be a good idea to implement some
    641 rate-limiting mechanism to prevent overflowing the logs with many duplicate
    642 copies of the same (or very similar) information.</li>
    643 <li>Losses of network connectivity are considered common, fully expected, and
    644 should not be logged gratuitously. A loss of network connectivity
    645 that has consequences within an app should be logged at the DEBUG or VERBOSE
    646 level (depending on whether the consequences are serious enough and unexpected
    647 enough to be logged in a release build).</li>
    648 <li>Having a full filesystem on a filesystem that is accessible to or on
    649 behalf of third-party applications should not be logged at a level higher than
    650 INFORMATIVE.</li>
    651 <li>Invalid data coming from any untrusted source (including any
    652 file on shared storage, or data coming through just about any network
    653 connection) is considered expected and should not trigger any logging at a
    654 level higher than DEBUG when it's detected to be invalid (and even then
    655 logging should be as limited as possible).</li>
    656 <li>Keep in mind that the <code>+</code> operator, when used on Strings,
    657 implicitly creates a <code>StringBuilder</code> with the default buffer size (16
    658 characters) and potentially other temporary String objects, i.e.
    659 that explicitly creating StringBuilders isn't more expensive than relying on
    660 the default '+' operator (and can be a lot more efficient in fact). Keep
    661 in mind that code that calls <code>Log.v()</code> is compiled and executed on
    662 release builds, including building the strings, even if the logs aren't being
    663 read.</li>
    664 <li>Any logging that is meant to be read by other people and to be
    665 available in release builds should be terse without being cryptic, and should
    666 be reasonably understandable. This includes all logging up to the DEBUG
    667 level.</li>
    668 <li>When possible, logging should be kept on a single line if it
    669 makes sense. Line lengths up to 80 or 100 characters are perfectly acceptable,
    670 while lengths longer than about 130 or 160 characters (including the length of
    671 the tag) should be avoided if possible.</li>
    672 <li>Logging that reports successes should never be used at levels
    673 higher than VERBOSE.</li>
    674 <li>Temporary logging used to diagnose an issue that is hard to reproduce should
    675 be kept at the DEBUG or VERBOSE level and should be enclosed by if blocks that
    676 allow for disabling it entirely at compile time.</li>
    677 <li>Be careful about security leaks through the log. Private
    678 information should be avoided. Information about protected content must
    679 definitely be avoided. This is especially important when writing framework
    680 code as it's not easy to know in advance what will and will not be private
    681 information or protected content.</li>
    682 <li><code>System.out.println()</code> (or <code>printf()</code> for native code)
    683 should never be used. System.out and System.err get redirected to /dev/null, so
    684 your print statements will have no visible effects. However, all the string
    685 building that happens for these calls still gets executed.</li>
    686 <li><em>The golden rule of logging is that your logs may not
    687 unnecessarily push other logs out of the buffer, just as others may not push
    688 out yours.</em></li>
    689 </ul>
    690 
    691 <h3 id="be-consistent">Be Consistent</h3>
    692 <p>Our parting thought: BE CONSISTENT. If you're editing code, take a few
    693 minutes to look at the surrounding code and determine its style. If that code
    694 uses spaces around the if clauses, you should too. If the code comments have
    695 little boxes of stars around them, make your comments have little boxes of stars
    696 around them too.</p>
    697 <p>The point of having style guidelines is to have a common vocabulary of
    698 coding, so people can concentrate on what you're saying, rather than on how
    699 you're saying it. We present global style rules here so people know the
    700 vocabulary, but local style is also important. If the code you add to a file
    701 looks drastically different from the existing code around it, it throws
    702 readers out of their rhythm when they go to read it. Try to avoid this.</p>
    703 
    704 <h2 id="javatests-style-rules">Javatests Style Rules</h2>
    705 <p>Follow test method naming conventions and use an underscore to separate what
    706 is being tested from the specific case being tested. This style makes it easier
    707 to see exactly what cases are being tested. For example:</p>
    708 <pre><code>testMethod_specificCase1 testMethod_specificCase2
    709 
    710 void testIsDistinguishable_protanopia() {
    711     ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    712     assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    713     assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
    714 }
    715 </code></pre>
    716 
    717   </body>
    718 </html>
    719