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 @SuppressWarnings("generic-cast") 509 List<String> 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