提交Android代码的格式

http://source.android.com/source/code-style.html#follow-field-naming-conventions

Code Style for Contributors

In this document

The code styles below are strict rules, not guidelines or recommendations.Contributions to Android that do not adhere to these rules are generally notaccepted. We recognize that not all existing code follows these rules, butwe expect all new code to be compliant.

Java Language Rules

Android follows standard Java coding conventions with the additional rulesdescribed below.

Don't Ignore Exceptions

It can be tempting to write code that completely ignores an exception, suchas:

void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) { }
}

Do not do this. While you may think your code will never encounter this errorcondition or that it is not important to handle it, ignoring exceptions as abovecreates mines in your code for someone else to trigger some day. You must handleevery Exception in your code in a principled way; the specific handling variesdepending on the case.

Anytime somebody has an empty catch clause they should have acreepy feeling. There are definitely times when it is actually the correctthing to do, but at least you have to think about it. In Java you can't escapethe creepy feeling. -James Gosling

Acceptable alternatives (in order of preference) are:

• Throw the exception up to the caller of your method.

  void setServerPort(String value) throws NumberFormatException {
      serverPort = Integer.parseInt(value);
  }
  

• Throw a new exception that's appropriate to your level of abstraction.

  void setServerPort(String value) throws ConfigurationException {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          throw new ConfigurationException("Port " + value + " is not valid.");
      }
  }
  

• Handle the error gracefully and substitute an appropriate value in thecatch {} block.

  /** Set port. If value is not a valid number, 80 is substituted. */
  
  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          serverPort = 80;  // default port for server
      }
  }
  

• Catch the Exception and throw a new RuntimeException. This isdangerous, so do it only if you are positive that if this error occurs theappropriate thing to do is crash.

  /** Set port. If value is not a valid number, die. */
  
  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          throw new RuntimeException("port " + value " is invalid, ", e);
      }
  }
  

  Note The original exception is passed to theconstructor for RuntimeException. If your code must compile under Java 1.3, youmust omit the exception that is the cause.

• As a last resort, if you are confident that ignoring the exception isappropriate then you may ignore it, but you must also comment why with a goodreason:

  /** If value is not a valid number, original port number is used. */
  void setServerPort(String value) {
      try {
          serverPort = Integer.parseInt(value);
      } catch (NumberFormatException e) {
          // Method is documented to just ignore invalid user input.
          // serverPort will just be unchanged.
      }
  }
  

Don't Catch Generic Exception

It can also be tempting to be lazy when catching exceptions and dosomething like this:

try {
    someComplicatedIOFunction();        // may throw IOException
    someComplicatedParsingFunction();   // may throw ParsingException
    someComplicatedSecurityFunction();  // may throw SecurityException
    // phew, made it all the way
} catch (Exception e) {                 // I'll just catch all exceptions
    handleError();                      // with one generic handler!
}

Do not do this. In almost all cases it is inappropriate to catch genericException or Throwable (preferably not Throwable because it includes Errorexceptions). It is very dangerous because it means that Exceptionsyou never expected (including RuntimeExceptions like ClassCastException) getcaught in application-level error handling. It obscures the failure handlingproperties of your code, meaning if someone adds a new type of Exception in thecode you're calling, the compiler won't help you realize you need to handle theerror differently. In most cases you shouldn't be handling different types ofexception the same way.

The rare exception to this rule is test code and top-level code where youwant to catch all kinds of errors (to prevent them from showing up in a UI, orto keep a batch job running). In these cases you may catch generic Exception(or Throwable) and handle the error appropriately. Think very carefully beforedoing this, though, and put in comments explaining why it is safe in this place.

Alternatives to catching generic Exception:

• Catch each exception separately as separate catch blocks after a singletry. This can be awkward but is still preferable to catching all Exceptions.Beware repeating too much code in the catch blocks.

• Refactor your code to have more fine-grained error handling, with multipletry blocks. Split up the IO from the parsing, handle errors separately in eachcase.

• Rethrow the exception. Many times you don't need to catch the exception atthis level anyway, just let the method throw it.

Remember: exceptions are your friend! When the compiler complains you'renot catching an exception, don't scowl. Smile: the compiler just made iteasier for you to catch runtime problems in your code.

Don't Use Finalizers

Finalizers are a way to have a chunk of code executed when an object isgarbage collected. While they can be handy for doing cleanup (particularly ofexternal resources), there are no guarantees as to when a finalizer will becalled (or even that it will be called at all).

Android doesn't use finalizers. In most cases, you can do whatyou need from a finalizer with good exception handling. If you absolutely needit, define a close() method (or the like) and document exactly when thatmethod needs to be called (see InputStream for an example). In this case it isappropriate but not required to print a short log message from the finalizer,as long as it is not expected to flood the logs.

Fully Qualify Imports

When you want to use class Bar from package foo,thereare two possible ways to import it:

• import foo.*;

  Potentially reduces the number of import statements.

• import foo.Bar;

  Makes it obvious what classes are actually used and the code is more readablefor maintainers.

Use import foo.Bar; for importing all Android code. An explicitexception is made for java standard libraries (java.util.*,java.io.*, etc.) and unit test code(junit.framework.*).

Java Library Rules

There are conventions for using Android's Java libraries and tools. In somecases, the convention has changed in important ways and older code might use adeprecated pattern or library. When working with such code, it's okay tocontinue the existing style. When creating new components however, never usedeprecated libraries.

Java Style Rules

Use Javadoc Standard Comments

Every file should have a copyright statement at the top, followed by packageand import statements (each block separated by a blank line) and finally theclass or interface declaration. In the Javadoc comments, describe what the classor interface does.

/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Does X and Y and provides an abstraction for Z.
 */

public class Foo {
    ...
}

Every class and nontrivial public method you write must contain aJavadoc comment with at least one sentence describing what the class or methoddoes. This sentence should start with a third person descriptive verb.

Examples:

/** Returns the correctly rounded positive square root of a double value. */
static double sqrt(double a) {
    ...
}

or

/**
 * Constructs a new String by converting the specified array of
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}

You do not need to write Javadoc for trivial get and set methods such assetFoo() if all your Javadoc would say is "sets Foo". If the methoddoes something more complex (such as enforcing a constraint or has an importantside effect), then you must document it. If it's not obvious what the property"Foo" means, you should document it.

Every method you write, public or otherwise, would benefit from Javadoc.Public methods are part of an API and therefore require Javadoc. Android doesnot currently enforce a specific style for writing Javadoc comments, but youshould follow the instructions Howto Write Doc Comments for the Javadoc Tool.

Write Short Methods

When feasible, keep methods small and focused. We recognize that long methodsare sometimes appropriate, so no hard limit is placed on method length. If amethod exceeds 40 lines or so, think about whether it can be broken up withoutharming the structure of the program.

Define Fields in Standard Places

Define fields either at the top of the file or immediately before themethods that use them.

Limit Variable Scope

Keep the scope of local variables to a minimum. By doing so, youincrease the readability and maintainability of your code and reduce thelikelihood of error. Each variable should be declared in the innermost blockthat encloses all uses of the variable.

Local variables should be declared at the point they are first used. Nearlyevery local variable declaration should contain an initializer. If you don'tyet have enough information to initialize a variable sensibly, postpone thedeclaration until you do.

The exception is try-catch statements. If a variable is initialized with thereturn value of a method that throws a checked exception, it must be initializedinside a try block. If the value must be used outside of the try block, then itmust be declared before the try block, where it cannot yet be sensiblyinitialized:

// Instantiate class cl, which represents some sort of Set
Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set
s.addAll(Arrays.asList(args));

However, even this case can be avoided by encapsulating the try-catch blockin a method:

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set
Set s = createSet(cl);
s.addAll(Arrays.asList(args));

Loop variables should be declared in the for statement itself unless thereis a compelling reason to do otherwise:

for (int i = 0; i < n; i++) {
    doSomething(i);
}

and

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}

Order Import Statements

The ordering of import statements is:

1. Android imports

2. Imports from third parties (com, junit,net, org)

3. java and javax

To exactly match the IDE settings, the imports should be:

• Alphabetical within each grouping, with capital letters before lower caseletters (e.g. Z before a).

• Separated by a blank line between each major grouping (android,com, junit, net, org,java, javax).

Originally, there was no style requirement on the ordering, meaning IDEs wereeither always changing the ordering or IDE developers had to disable theautomatic import management features and manually maintain the imports. This wasdeemed bad. When java-style was asked, the preferred styles varied wildly and itcame down to Android needing to simply "pick an ordering and be consistent." Sowe chose a style, updated the style guide, and made the IDEs obey it. We expectthat as IDE users work on the code, imports in all packages will match thispattern without extra engineering effort.

This style was chosen such that:

• The imports people want to look at first tend to be at the top(android).

• The imports people want to look at least tend to be at the bottom(java).

• Humans can easily follow the style.

• IDEs can follow the style.

The use and location of static imports have been mildly controversialissues. Some people prefer static imports to be interspersed with theremaining imports, while some prefer them to reside above or below allother imports. Additionally, we have not yet determined how to make all IDEs usethe same ordering. Since many consider this a low priority issue, just use yourjudgement and be consistent.

Use Spaces for Indentation

We use four (4) space indents for blocks and never tabs. When in doubt, beconsistent with the surrounding code.

We use eight (8) space indents for line wraps, including function calls andassignments. For example, this is correct:

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

and this is not correct:

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

Follow Field Naming Conventions

• Non-public, non-static field names start with m.

• Static field names start with s.

• Other fields start with a lower case letter.

• Public static final fields (constants) are ALL_CAPS_WITH_UNDERSCORES.

For example:

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

Use Standard Brace Style

Braces do not go on their own line; they go on the same line as the codebefore them:

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

We require braces around the statements for a conditional. Exception: If theentire conditional (the condition and the body) fit on one line, you may (butare not obligated to) put it all on one line. For example, this is acceptable:

if (condition) {
    body();
}

and this is acceptable:

if (condition) body();

but this is not acceptable:

if (condition)
    body();  // bad!

Limit Line Length

Each line of text in your code should be at most 100 characters long. Whilemuch discussion has surrounded this rule, the decision remains that 100characters is the maximum with the following exceptions:

• If a comment line contains an example command or a literal URLlonger than 100 characters, that line may be longer than 100 characters forease of cut and paste.
• Import lines can go over the limit because humans rarely see them (this alsosimplifies tool writing).

Use Standard Java Annotations

Annotations should precede other modifiers for the same language element.Simple marker annotations (e.g. @Override) can be listed on the same line withthe language element. If there are multiple annotations, or parameterizedannotations, they should each be listed one-per-line in alphabeticalorder.

Android standard practices for the three predefined annotations in Java are:

• @Deprecated: The @Deprecated annotation must be used wheneverthe use of the annotated element is discouraged. If you use the @Deprecatedannotation, you must also have a @deprecated Javadoc tag and it should name analternate implementation. In addition, remember that a @Deprecated method isstill supposed to work. If you see old code that has a @deprecatedJavadoc tag, please add the @Deprecated annotation.
• @Override: The @Override annotation must be used whenever amethod overrides the declaration or implementation from a super-class. Forexample, if you use the @inheritdocs Javadoc tag, and derive from a class (notan interface), you must also annotate that the method @Overrides the parentclass's method.
• @SuppressWarnings: The @SuppressWarnings annotation should beused only under circumstances where it is impossible to eliminate a warning. Ifa warning passes this "impossible to eliminate" test, the @SuppressWarningsannotation must be used, so as to ensure that all warnings reflectactual problems in the code.

  When a @SuppressWarnings annotation is necessary, it must be prefixed witha TODO comment that explains the "impossible to eliminate" condition. Thiswill normally identify an offending class that has an awkward interface. Forexample:

  // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
  @SuppressWarnings("generic-cast")
  List<String> blix = Utility.rotate(blax);
  

  When a @SuppressWarnings annotation is required, the code should berefactored to isolate the software elements where the annotation applies.

Treat Acronyms as Words

Treat acronyms and abbreviations as words in naming variables, methods, andclasses to make names more readable:

Good	Bad
XmlHttpRequest	XMLHTTPRequest
getCustomerId	getCustomerID
class Html	class HTML
String url	String URL
long id	long ID

As both the JDK and the Android code bases are very inconsistent aroundacronyms, it is virtually impossible to be consistent with the surroundingcode. Therefore, always treat acronyms as words.

Use TODO Comments

Use TODO comments for code that is temporary, a short-term solution, orgood-enough but not perfect. TODOs should include the string TODO in all caps,followed by a colon:

// TODO: Remove this code after the UrlTable2 has been checked in.

and

// TODO: Change this to use a flag instead of a constant.

If your TODO is of the form "At a future date do something" make sure thatyou either include a very specific date ("Fix by November 2005") or a veryspecific event ("Remove this code after all production mixers understandprotocol V7.").

Log Sparingly

While logging is necessary, it has a significantly negative impact onperformance and quickly loses its usefulness if not kept reasonablyterse. The logging facilities provides five different levels of logging:

• ERROR:Use when something fatal has happened, i.e. something will have user-visibleconsequences and won't be recoverable without explicitly deleting some data,uninstalling applications, wiping the data partitions or reflashing the entiredevice (or worse). This level is always logged. Issues that justify some loggingat the ERROR level are typically good candidates to be reported to astatistics-gathering server.
• WARNING:Use when something serious and unexpected happened, i.e. something that willhave user-visible consequences but is likely to be recoverable without data lossby performing some explicit action, ranging from waiting or restarting an appall the way to re-downloading a new version of an application or rebooting thedevice. This level is always logged. Issues that justify some logging at theWARNING level might also be considered for reporting to a statistics-gatheringserver.
• INFORMATIVE:Use to note that something interesting to most people happened, i.e. when asituation is detected that is likely to have widespread impact, though isn'tnecessarily an error. Such a condition should only be logged by a module thatreasonably believes that it is the most authoritative in that domain (to avoidduplicate logging by non-authoritative components). This level is always logged.
• DEBUG:Use to further note what is happening on the device that could be relevant toinvestigate and debug unexpected behaviors. You should log only what is neededto gather enough information about what is going on about your component. Ifyour debug logs are dominating the log then you probably should be using verboselogging.

  This level will be logged, even on release builds, and is required to besurrounded by an if (LOCAL_LOG) or if (LOCAL_LOGD)block, where LOCAL_LOG[D] is defined in your class or subcomponent,so that there can exist a possibility to disable all such logging. There musttherefore be no active logic in an if (LOCAL_LOG) block. All thestring building for the log also needs to be placed inside the if(LOCAL_LOG) block. The logging call should not be re-factored out into amethod call if it is going to cause the string building to take place outsideof the if (LOCAL_LOG) block.

  There is some code that still says if (localLOGV). This isconsidered acceptable as well, although the name is nonstandard.

• VERBOSE:Use for everything else. This level will only be logged on debug builds andshould be surrounded by an if (LOCAL_LOGV) block (or equivalent) soit can be compiled out by default. Any string building will be stripped out ofrelease builds and needs to appear inside the if (LOCAL_LOGV) block.

Notes:

• Within a given module, other than at the VERBOSE level, anerror should only be reported once if possible. Within a single chain offunction calls within a module, only the innermost function should return theerror, and callers in the same module should only add some logging if thatsignificantly helps to isolate the issue.
• In a chain of modules, other than at the VERBOSE level, when alower-level module detects invalid data coming from a higher-level module, thelower-level module should only log this situation to the DEBUG log, and onlyif logging provides information that is not otherwise available to the caller.Specifically, there is no need to log situations where an exception is thrown(the exception should contain all the relevant information), or where the onlyinformation being logged is contained in an error code. This is especiallyimportant in the interaction between the framework and applications, andconditions caused by third-party applications that are properly handled by theframework should not trigger logging higher than the DEBUG level. The onlysituations that should trigger logging at the INFORMATIVE level or higher iswhen a module or application detects an error at its own level or coming froma lower level.
• When a condition that would normally justify some logging islikely to occur many times, it can be a good idea to implement somerate-limiting mechanism to prevent overflowing the logs with many duplicatecopies of the same (or very similar) information.
• Losses of network connectivity are considered common, fully expected, andshould not be logged gratuitously. A loss of network connectivitythat has consequences within an app should be logged at the DEBUG or VERBOSElevel (depending on whether the consequences are serious enough and unexpectedenough to be logged in a release build).
• Having a full filesystem on a filesystem that is accessible to or onbehalf of third-party applications should not be logged at a level higher thanINFORMATIVE.
• Invalid data coming from any untrusted source (including anyfile on shared storage, or data coming through just about any networkconnection) is considered expected and should not trigger any logging at alevel higher than DEBUG when it's detected to be invalid (and even thenlogging should be as limited as possible).
• Keep in mind that the + operator, when used on Strings,implicitly creates a StringBuilder with the default buffer size (16characters) and potentially other temporary String objects, i.e.that explicitly creating StringBuilders isn't more expensive than relying onthe default '+' operator (and can be a lot more efficient in fact). Keepin mind that code that calls Log.v() is compiled and executed onrelease builds, including building the strings, even if the logs aren't beingread.
• Any logging that is meant to be read by other people and to beavailable in release builds should be terse without being cryptic, and shouldbe reasonably understandable. This includes all logging up to the DEBUGlevel.
• When possible, logging should be kept on a single line if itmakes sense. Line lengths up to 80 or 100 characters are perfectly acceptable,while lengths longer than about 130 or 160 characters (including the length ofthe tag) should be avoided if possible.
• Logging that reports successes should never be used at levelshigher than VERBOSE.
• Temporary logging used to diagnose an issue that is hard to reproduce shouldbe kept at the DEBUG or VERBOSE level and should be enclosed by if blocks thatallow for disabling it entirely at compile time.
• Be careful about security leaks through the log. Privateinformation should be avoided. Information about protected content mustdefinitely be avoided. This is especially important when writing frameworkcode as it's not easy to know in advance what will and will not be privateinformation or protected content.
• System.out.println() (or printf() for native code)should never be used. System.out and System.err get redirected to /dev/null, soyour print statements will have no visible effects. However, all the stringbuilding that happens for these calls still gets executed.
• The golden rule of logging is that your logs may notunnecessarily push other logs out of the buffer, just as others may not pushout yours.

Be Consistent

Our parting thought: BE CONSISTENT. If you're editing code, take a fewminutes to look at the surrounding code and determine its style. If that codeuses spaces around the if clauses, you should too. If the code comments havelittle boxes of stars around them, make your comments have little boxes of starsaround them too.

The point of having style guidelines is to have a common vocabulary ofcoding, so people can concentrate on what you're saying, rather than on howyou're saying it. We present global style rules here so people know thevocabulary, but local style is also important. If the code you add to a filelooks drastically different from the existing code around it, it throwsreaders out of their rhythm when they go to read it. Try to avoid this.

Javatests Style Rules

Follow test method naming conventions and use an underscore to separate whatis being tested from the specific case being tested. This style makes it easierto see exactly what cases are being tested. For example:

testMethod_specificCase1 testMethod_specificCase2

void testIsDistinguishable_protanopia() {
    ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}