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