zh-cn/source/code-style.html

<html devsite><head>
    <title></title>
    <meta name="project_path" value="/_project.yaml"/>
    <meta name="book_path" value="/_book.yaml"/>
  </head>
  <body>
  <!--
      Copyright 2017 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.
  -->

<p> Android <em></em></p>

<h2 id="java-language-rules">Java </h2>
<p>Android  Java </p>

<h3 id="dont-ignore-exceptions"></h3>
<p></p>
<pre><code>void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) { }
}
</code></pre>
<p></p>
<p><em> catch  catch  Java </em>-<a href="http://www.artima.com/intv/solid4.html">James Gosling</a></p>
<p></p>
<ul>
<li>
<pre><code>void setServerPort(String value) throws NumberFormatException {
    serverPort = Integer.parseInt(value);
}
</code></pre>
</li>
<li>
<pre><code>void setServerPort(String value) throws ConfigurationException {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        throw new ConfigurationException("Port " + value + " is not valid.");
    }
}
</code></pre>
</li>
<li> catch {}
<pre><code>/** 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
    }
}
</code></pre>
</li>
<li> <code>RuntimeException</code>
<pre><code>/** 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);
    }
}
</code></pre>
<p class="note"><strong></strong> RuntimeException  Java 1.3 </p>
</li>
<li><pre><code>/** 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.
    }
}
</code></pre>
</li>
</ul>

<h3 id="dont-catch-generic-exception"></h3>
<p></p>
<pre><code>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!
}
</code></pre>
<p> Throwable Throwable Error  ClassCastException  RuntimeException</p>
<p> Throwable</p>
<p></p>
<ul>
<li>
<p> try  catch  catch </p></li><p></p>

<li>
<p> try  IO</p>
</li>
<li>
<p></p>
</li>
</ul>
<p></p>
<h3 id="dont-use-finalizers"></h3>
<p></p>
<p>Android  close()  InputStream</p>

<h3 id="fully-qualify-imports"></h3>
<p> foo  Bar </p>
<ul>
<li><code>import foo.*;</code>
<p> import </p></li>
<li><code>import foo.Bar;</code>
<p></p></li></ul>
<p> <code>import foo.Bar;</code>  Android  Java <code>java.util.*</code><code>java.io.*</code>  (<code>junit.framework.*</code>) </p>

<h2 id="java-library-rules">Java </h2>
<p> Android  Java </p>

<h2 id="java-style-rules">Java </h2>

<h3 id="use-javadoc-standard-comments"> Javadoc </h3>
<p> package  import  Javadoc </p>
<pre><code>/*
 * 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 {
    ...
}
</code></pre>
<p><em></em> Javadoc </p>
<p></p>
<pre><code>/** Returns the correctly rounded positive square root of a double value. */
static double sqrt(double a) {
    ...
}
</code></pre>
<p></p>
<pre><code>/**
 * Constructs a new String by converting the specified array of
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
    ...
}
</code></pre>
<p> get  set  <code>setFoo()</code> Javadoc FooFoo
</p><p> Javadoc API  JavadocAndroid  Javadoc <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html"> Javadoc </a></p>

<h3 id="write-short-methods"></h3>
<p> 40 </p>

<h3 id="define-fields-in-standard-places"></h3>
<p></p>

<h3 id="limit-variable-scope"></h3>
<p></p>
<p></p>
<p>try-catch  try  try  try  try </p>
<pre><code>// 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));
</code></pre>
<p> try-catch </p>
<pre><code>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));
</code></pre>
<p> for </p>
<pre><code>for (int i = 0; i &lt; n; i++) {
    doSomething(i);
}
</code></pre>
<p></p>
<pre><code>for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}
</code></pre>

<h3 id="order-import-statements"> import </h3>
<p>import </p>
<ol>
<li>
<p> Android </p>
</li>
<li>
<p><code>com</code><code>junit</code><code>net</code><code>org</code></p>
</li>
<li>
<p><code>java</code>  <code>javax</code></p>
</li>
</ol>
<p> IDE </p>
<ul>
<li>
<p> Z  a </p>
</li>
<li>
<p><code>android</code><code>com</code><code>junit</code><code>net</code><code>org</code><code>java</code><code>javax</code></p>
</li>
</ul>
<p> IDE  IDE  Java  Android  IDE  IDE </p>
<p></p>
<ul>
<li>
<p> (<code>android</code>)</p>
</li>
<li>
<p> (<code>java</code>)</p>
</li>
<li>
<p></p>
</li>
<li>
<p>IDE </p>
</li>
</ul>
<p> IDE </p>

<h3 id="use-spaces-for-indentation"></h3>
<p> (4) </p>
<p> (8) </p>
<pre><code>Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);
</code></pre>
<p></p>
<pre><code>Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);
</code></pre>

<h3 id="follow-field-naming-conventions"></h3>
<ul>
<li>
<p> m </p>
</li>
<li>
<p> s </p>
</li>
<li>
<p></p>
</li>
<li>
<p> final  (ALL_CAPS_WITH_UNDERSCORES)</p>
</li>
</ul>
<p></p>
<pre><code>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;
}
</code></pre>
<h3 id="use-standard-brace-style"></h3>
<p></p>
<pre><code>class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}
</code></pre>
<p></p>
<pre><code>if (condition) {
    body();
}
</code></pre>
<p></p>
<pre><code>if (condition) body();
</code></pre>
<p></p>
<pre><code>if (condition)
    body();  // bad!
</code></pre>

<h3 id="limit-line-length"></h3>
<p> 100 <em></em> 100 </p>
<ul>
<li> 100  100 </li>
<li></li>
</ul>

<h3 id="use-standard-java-annotations"> Java </h3>
<p> @Override</p>
<p>Java  3  Android </p>
<ul>
<li><code>@Deprecated</code> @Deprecated  @Deprecated  @deprecated Javadoc @Deprecated <em></em> @deprecated Javadoc  @Deprecated
</li>
<li><code>@Override</code> @Override  @inheritdocs Javadoc  @Override </li>
<li><code>@SuppressWarnings</code>@SuppressWarnings <em></em> @SuppressWarnings
<p> @SuppressWarnings  TODO </p>
<pre><code>// TODO: The third-party class com.third.useful.Utility.rotate() needs generics
@SuppressWarnings("generic-cast")
List&lt;String&gt; blix = Utility.rotate(blax);
</code></pre>
<p> @SuppressWarnings </p>
</li>
</ul>

<h3 id="treat-acronyms-as-words"></h3>
<p></p>
<table>
<thead>
<tr>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>XmlHttpRequest</td>
<td>XMLHTTPRequest</td>
</tr>
<tr>
<td>getCustomerId</td>
<td>getCustomerID</td>
</tr>
<tr>
<td>class Html</td>
<td>class HTML</td>
</tr>
<tr>
<td>String url</td>
<td>String URL</td>
</tr>
<tr>
<td>long id</td>
<td>long ID</td>
</tr>
</tbody>
</table>
<p> JDK  Android </p>

<h3 id="use-todo-comments"> TODO </h3>
<p> TODO TODO  TODO </p>
<pre><code>// TODO: Remove this code after the UrlTable2 has been checked in.
</code></pre>
<p></p>
<pre><code>// TODO: Change this to use a flag instead of a constant.
</code></pre>
<p> TODO  2005  11  V7 </p>

<h3 id="log-sparingly"></h3>
<p> 5 </p>
<ul>
<li><code>ERROR</code> ERROR </li>
<li><code>WARNING</code> WARNING </li>
<li><code>INFORMATIVE:</code>
</li>
<li><code>DEBUG</code> VERBOSE
<p> <code>if (LOCAL_LOG)</code>  <code>if (LOCAL_LOGD)</code>  <code>LOCAL_LOG[D]</code> <code>if (LOCAL_LOG)</code>  <code>if
(LOCAL_LOG)</code>  <code>if (LOCAL_LOG)</code> </p>
<p> <code>if (localLOGV)</code></p>
</li>
<li><code>VERBOSE</code> <code>if (LOCAL_LOGV)</code>  <code>if (LOCAL_LOGV)</code>
</li>
</ul>
<p><em></em> </p>
<ul>
<li> VERBOSE </li>
<li> VERBOSE  DEBUG  DEBUG  INFORMATIVE </li>
<li></li>
<li> DEBUG  VERBOSE </li>
<li> INFORMATIVE </li>
<li> DEBUG </li>
<li> String  <code>+</code>  16  <code>StringBuilder</code> String  StringBuilder + <code>Log.v()</code> </li>
<li> DEBUG </li>
<li> 80  100  130  160 </li>
<li> VERBOSE </li>
<li> DEBUG  VERBOSE  if </li>
<li></li>
<li> <code>System.out.println()</code> <code>printf()</code>System.out  System.err  /dev/null print </li>
<li><em></em></li>
</ul>

<h3 id="be-consistent"></h3>
<p> if </p>
<p></p>

<h2 id="javatests-style-rules">Javatests </h2>
<p></p>
<pre><code>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))
}
</code></pre>

</body></html>