m是member的缩写,不是my的缩写。
其它还有:
做了一个简单的翻译。
——————————————————————————————————
Code Style Guidelines for Contributors
In this document
Follow Test Method Naming Conventions
遵循测试方法命名约定
The rules below are not guidelines or recommendations, but strict rules. Contributions to Android generally will not be accepted if they do not adhere to these rules.
Not all existing code follows these rules, but all new code is expected to.
以下规则不是指导或是推荐性质,而是严格的规则。一般来说,如果不遵守这些规则,你对Android贡献的代码将不会被接受。
不是所有存在的代码都遵循这些规则,但是期待所有新代码都遵循这些规则。
Java Language Rules
Java语言规则
We follow standard Java coding conventions. We add a few rules:
我们遵循标准的Java代码约定,我们添加了一些规则。
Don't Ignore Exceptions
不要忽略异常
Sometimes it is tempting to write code that completely ignores an exception like this:
void setServerPort(String value) {
try {
serverPort = Integer.parseInt(value);
} catch (NumberFormatException e) { }
}
You must never do this. While you may think that your code will never encounter this error condition or that it is not important to handle it, ignoring exceptions like above creates mines in your code for someone else to trip over some day. You must handle every Exception in your code in some principled way. The specific handling varies depending on the case.
Anytime somebody has an empty catch clause they should have a creepy feeling. There are definitely times when it is actually the correct thing to do, but at least you have to think about it. In Java you can't escape the creepy feeling. -James Gosling
Acceptable alternatives (in order of preference) are:
Don't Catch Generic Exception
Sometimes it is tempting to be lazy when catching exceptions and do something 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!
}
You should not do this. In almost all cases it is inappropriate to catch generic Exception or Throwable, preferably not Throwable, because it includes Error exceptions as well. It is very dangerous. It means that Exceptions you never expected (including RuntimeExceptions like ClassCastException) end up getting caught in application-level error handling. It obscures the failure handling properties of your code. It means if someone adds a new type of Exception in the code you're calling, the compiler won't help you realize you need to handle that error differently. And in most cases you shouldn't be handling different types of exception the same way, anyway.
There are rare exceptions to this rule: certain test code and top-level code where you want to catch all kinds of errors (to prevent them from showing up in a UI, or to keep a batch job running). In that case you may catch generic Exception (or Throwable) and handle the error appropriately. You should think very carefully before doing this, though, and put in comments explaining why it is safe in this place.
Alternatives to catching generic Exception:
Remember: exceptions are your friend! When the compiler complains you're not catching an exception, don't scowl. Smile: the compiler just made it easier 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 is garbage collected.
Pros: can be handy for doing cleanup, particularly of external resources.
Cons: there are no guarantees as to when a finalizer will be called, or even that it will be called at all.
Decision: we don't use finalizers. In most cases, you can do what you need from a finalizer with good exception handling. If you absolutely need it, define a close() method (or the like) and document exactly when that method needs to be called. See InputStream for an example. In this case it is appropriate 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,there are two possible ways to import it:
当你想使用包foo中的类Bar时,有两种可能的方式来导入:
Pros: Potentially reduces the number of import statements.
好处:减少了导入语句的数量
Pros: Makes it obvious what classes are actually used. Makes code more readable for maintainers.
好处:显示了所使用的具体类。使代码更可读。
Decision: Use the latter for importing all Android code. An explicit exception is made for java standard libraries (java.util.*, java.io.*, etc.) and unit test code (junit.framework.*)
决定:使用后者来导入所有的Android代码。对于Java标准库和单元代码例外。
Java Library Rules
There are conventions for using Android's Java libraries and tools. In some cases, the convention has changed in important ways and older code might use a deprecated pattern or library. When working with such code, it's okay to continue the existing style. When creating new components never use deprecated libraries.
Java Style Rules
Use Javadoc Standard Comments
Every file should have a copyright statement at the top. Then a package statement and import statements should follow, each block separated by a blank line. And then there is the class or interface declaration. In the Javadoc comments, describe what the class or interface does.
/*
* Copyright (C) 2013 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 a Javadoc comment with at least one sentence describing what the class or method does. This sentence should start with a 3rd 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 as setFoo() if all your Javadoc would say is "sets Foo". If the method does something more complex (such as enforcing a constraint or having an important side effect), then you must document it. And if it's not obvious what the property "Foo" means, you should document it.
Every method you write, whether public or otherwise, would benefit from Javadoc. Public methods are part of an API and therefore require Javadoc.
Android does not currently enforce a specific style for writing Javadoc comments, but you should follow the instructions How to Write Doc Comments for the Javadoc Tool.
Write Short Methods
书写简短的方法
To the extent that it is feasible, methods should be kept small and focused. It is, however, recognized that long methods are sometimes appropriate, so no hard limit is placed on method length. If a method exceeds 40 lines or so, think about whether it can be broken up without harming the structure of the program.
Define Fields in Standard Places
在标准的位置定义字段
Fields should be defined either at the top of the file, or immediately before the methods that use them.
字段应该定义在文件的开头,或者定义在紧临使用该字段的方法之前。
Limit Variable Scope
限制变量的作用域
The scope of local variables should be kept to a minimum. By doing so, you increase the readability and maintainability of your code and reduce the likelihood of error. Each variable should be declared in the innermost block that encloses all uses of the variable.
Local variables should be declared at the point they are first used. Nearly every local variable declaration should contain an initializer. If you don't yet have enough information to initialize a variable sensibly, you should postpone the declaration until you do.
One exception to this rule concerns try-catch statements. If a variable is initialized with the return value of a method that throws a checked exception, it must be initialized inside a try block. If the value must be used outside of the try block, then it must be declared before the try block, where it cannot yet be sensibly initialized:
// 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));
But even this case can be avoided by encapsulating the try-catch block in 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 there is 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: 导入语句的顺序是:
To exactly match the IDE settings, the imports should be:
Originally there was no style requirement on the ordering. This meant that the IDE's were either always changing the ordering, or IDE developers had to disable the automatic import management features and maintain the imports by hand. This was deemed bad. When java-style was asked, the preferred styles were all over the map. It pretty much came down to our needing to "pick an ordering and be consistent." So we chose a style, updated the style guide, and made the IDEs obey it. We expect that as IDE users work on the code, the imports in all of the packages will end up matching this pattern without any extra engineering effort.
This style was chosen such that:
The use and location of static imports have been mildly controversial issues. Some people would prefer static imports to be interspersed with the remaining imports, some would prefer them reside above or below all other imports. Additionally, we have not yet come up with a way to make all IDEs use the same ordering.
Since most people consider this a low priority issue, just use your judgement and please be consistent.
Use Spaces for Indentation
缩进的空格数量
We use 4 space indents for blocks. We never use tabs. When in doubt, be consistent with code around you.
We use 8 space indents for line wraps, including function calls and assignments. 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
字段命名约定
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 code before them. So:
括号不独占一行,而是和它们前面的代码在同一行。所以:
class MyClass {
int func() {
if (something) {
// ...
} else if (somethingElse) {
// ...
} else {
// ...
}
}
}
We require braces around the statements for a conditional. Except, if the entire conditional (the condition and the body) fit on one line, you may (but are not obligated to) put it all on one line. That is, this is legal:
除非全部条件语句(条件和条件体)在一行,否则需要使花括号包围条件体。也就是说,这是合规的:
if (condition) {
body();
}
and this is legal: 这也是合规的:
if (condition) body();
but this is still illegal: 但是这是不合规的:
if (condition)
body(); // bad!
Limit Line Length
限制每行的长度
Each line of text in your code should be at most 100 characters long.
每行的文字长度最长为100个字符。
There has been lots of discussion about this rule and the decision remains that 100 characters is the maximum.
对于这条规则,有很多的争论,但是决定仍然保持100个字符为最大长度。
Exception: if a comment line contains an example command or a literal URL longer than 100 characters, that line may be longer than 100 characters for ease of cut and paste.
Exception: import lines can go over the limit because humans rarely see them. This also simplifies tool writing.
Use Standard Java Annotations
使用标准的Java注解
Annotations should precede other modifiers for the same language element. Simple marker annotations (e.g. @Override) can be listed on the same line with the language element. If there are multiple annotations, or parameterized annotations, they should each be listed one-per-line in alphabetical order.<
Android standard practices for the three predefined annotations in Java are:
Treat Acronyms as Words
把缩写词看作一个单词
Treat acronyms and abbreviations as words in naming variables, methods, and classes. The names are much more readable:
在命名变量、方法、类的时候,把缩写词看作是一个词。这样名称可读性更强:(acronym :首字母缩写词HTML;abbreviation:缩写词 ID)
Good |
Bad |
XmlHttpRequest |
XMLHTTPRequest |
getCustomerId |
getCustomerID |
class Html |
class HTML |
String url |
String URL |
long id |
long ID |
Both the JDK and the Android code bases are very inconsistent with regards to acronyms, therefore, it is virtually impossible to be consistent with the code around you. Bite the bullet, and treat acronyms as words.
JDK和Android的代码库对于缩写词上非常不一致,因此它也几乎不可能与你周围的代码一致。硬着头皮,把缩写看作一个单词吧。
Use TODO Comments
使用TODO的注释
Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.
对代码使用TODO注释是临时的,短期的解决方案,或者说是足够好但不完美的。
TODOs should include the string TODO in all caps, followed by a colon:
TODO应该包含都是大写的TODO字符串,接着根着一个冒号:
// 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 that you either include a very specific date ("Fix by November 2005") or a very specific event ("Remove this code after all production mixers understand protocol V7.").
Log Sparingly
谨慎的使用日志
While logging is necessary, it has a significantly negative impact on performance and quickly loses its usefulness if it's not kept reasonably terse. The logging facilities provides five different levels of logging:
日志是必需的,但是如果不保持精练,它也会明显的影响性能表现,快速的推动了它的有效性。日志组件提供了五种不同标准的日志。
Notes:
Be Consistent
风格一致
Our parting thought: BE CONSISTENT. If you're editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around their if clauses, you should too. If their comments have little boxes of stars around them, make your comments have little boxes of stars around them too.
最后一条,我们认为:风格一致。如果你在编写代码,花几分钟看看你周围的代码并决定它的风格。如果他们在条件子句外包有空格,你应该也这样做。如果他们的注释没有星号条包围,让你的注释代码也没有星号条包围。
The point of having style guidelines is to have a common vocabulary of coding, so people can concentrate on what you're saying, rather than on how you're saying it. We present global style rules here so people know the vocabulary. But local style is also important. If code you add to a a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Try to avoid this.
Javatests Style Rules
Follow Test Method Naming Conventions
遵循测试方法命名约定
When naming test methods, you can use an underscore to seperate what is being tested from the specific case being tested. This style makes it easier to 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))
}
Except as noted, this content is licensed under Creative Commons Attribution 2.5. For details and restrictions, see the Content License.
About Android | Community | Legal |
从 <http://source.android.com/source/code-style.html#follow-field-naming-conventions> 插入