Java编码规范（The Elements of Java Style）

Genaral Principles 一般约定

1.Adhere to the style
of the original.

保持最初的样式。

2.Adhere to the Principle of Least
Astonishment.

遵守最小惊奇原则。

3.Do it right the first time.

第一次就应当做好。

4.Document any deviations.

对于任何背离都应当文档注释。

Formatting
Conventions 格式约定

5.Indent nested code.

约束嵌套代码。

6.Break up long lines.

拆分长行。

7.Include white space.

包含空格。

8.Do not use "hard" tabs.

不要使用tab键。

Naming
Conventions 命名约定

9.Use meaningful names.

使用有意义的名称。

10.Use familiar names.

使用熟悉的名称。

11.Question excessively
long names.

不要使用过长的名称。

12.Join the vowel generation.

加入元音字母。

13.Capitalize only the first letter in acronyms.

只对简称的第一个字母大写。

14.Do not use names that differ only in case.

不要使用只依赖于大小写来区分的名称。

Package Names 包命名

15.Use
the reversed, lowercase form of your organization's Internet domain
name as the root qualifier for your package names.

采用你组织的Internet域名
的反转、小写形式作为包名称的根限定词。

16.Use a single, lowercase word as the root
name of each package.

使用一个唯一的小写单词作为每个包的根名称。

17.Use the
same name for a new version of a package, but only if that new version
is still binary compatible with the previous versin, otherwise, use a
new name.

只有当包的新版本仍然与旧版本兼容时，对于包的新版本使用相同的名称，否则使用新名称。


Type Names 类型命名

18.Capitalize the first letter of
each word that appears in a class or interface name.

对于类和接口名称只对每个单词
的第一个字母大写。

Class Names 类命名

19.Use
nouns when naming classes.

使用名词来命名类。

20.Pluralize the
names of classes that group related attributes, static services, or
constants.

对于成组的相关属性、静态服务和常量，类名称采用复数形式。

Interface
Names 接口命名

21.Use nouns or adjectives when naming
interfaces.

使用名词或形容词来命名接口。

Method Names 方法命名

22.Use
lowercase for the first word and capitalize only the first letter of
each subsequent word that appears in a method name.]

方法名称中第一个单词小写，后
续的每一个单词仅第一个字母大写。

23.Use verbs when naming methods.

使用动词来命名
方法。

24.Follow the JavaBeans conventions for naming property
accessor methods.

命名属性访问方法遵守JavaBeans约定。

Variable
Names 变量命名

25.Use lowercase for the first word and
capitalize only the first letter of each subsequent word that appears in
a variable name.

变量名称中第一个单词小写，后续的每一个单词仅第一个字母大写。

26.Use
nouns to name fields.

使用名词来命名成员变量。

27.Pluralize the names
of collection reference.

对于集合引用的名称采用复数形式。

28.Establish
and use a set of standard names for trivial "throwaway" variables.

对
于通常的临时变量，建立并使用一套标准名称。

Field Names 成员命名

29.Qualify field variables with "this" to distinguish them from local
variables.

使用“this”限定成员变量以同局部变量区分。

Parameter
Names 参数命名

30.When a constructor or "set" method
assigns a parameter to a field, give that parameter the same name as the
field.

当构造函数或者“set”方法向成员分配参数时，参数的命名应和成员相同。

Constant
Names 常量命名

31.Use uppercase letters for each word and
separate each pair of words with an underscore when naming constants.

当
命名常量时，每个单词均大写，单词之间以下划线区分。

Documentation Conventions 文档约定

32.Write documentation for those who must use your code and those must
maintain it.

为那些使用你代码和维护它的人写文档。

33.Keep comments and code
in sync.

保持注释与代码同步。

34.Use the active voice and omit
needless words.

使用积极的语气，忽略无用的单词。

Comment Types 注释类型

35.Use
documentation comments to describe the programing interface.

使用文档注
释来描述程序接口。

36.Use standard comments to hide code without
removing it.

使用标准注释来隐藏代码而不是删除。

37.Use one-line comments to
explain implementation details.

使用单行注释来解释实现细节。

Documentation
Comments 文档注释

38.Describe the programing interface
before you write the code.

在写代码之前描述程序接口。

39.Document
public, protected, package, and private members.

对public、protected、
package和private成员进行文档注释。

40.Provide a summary description and
overview for each package.

对每一个包提供概述。

41.Provide a
summary description and overview for each application or group of
packages.

对每一个应用或者包的组提供概述。

Comment Style 注释样式

42.Use a single consistent format and organization for all
documentation comments.

对于所有的文档注释坚持使用一种格式。

43.Wrap
keywords, identifiers, and constants with <code>...</code>
tags.

使用<code>...</code>标记包装关键字、识别符和常量。

44.Wrap code with <pre>...</pre> tags.

使用<pre>...</pre>标记包装代码。

45.Consider marking the
first occurrence of an identifier with a {@link} tag.

考虑在标识符第一次出现时使用{@link}标记。

46.Establish and use a fixed ordering
for Javadoc tags.

对于Javadoc标记应该建立并使用一种固定的顺序。

47.Write
in the third-person narrative form.

以第三人称的叙述形式写。

48.Write summary descriptions that stand alone.

写概述应该独立。

49.Omit the subject in summary descriptions of actions or services.

在概述中忽略目标。

50.Omit the subject and the verb in summary
descriptions of things.

在事物的概述中忽略目标和动词。

51.Use "this"
rather than "the" when referring to instance of current class.

当指代当前类的实例时，用“this”而不是“the”。

52.Do not add parentheses to a
method or constructor name unless you want to specify a particular
signature.

不要对方法或构造函数名增加括号，除非你想表示特定的签名。

Comment
Content 注释内容

53.Provide a summary description for
each method.

给每一个方法提供概述。

54.Fully describe the signature
of each method.

完整描述每一方法签名。

55.Include examples.

包含示例。

56.Document preconditions, postconditions, and invariant
conditions.

对前置、后置、不变条件进行文档注释。

57.Document known
defects and deficiencies.

对已知的缺陷和不足进行文档注释。

58.Document synchronization semantics.

对同步语法进行文档注释。


Internal Comments 内部注释

59.Add internal comments only
if they will aid others in understanding your code.

只有当内部注释有助于其他人理解
你的代码时才添加。

60.Describe why the code is doing what it does, not
what the code is doing.

描述代码为什么那样做，而不是做了什么。

61.Avoid the
use of end-line comments.

避免使用行尾注释。

62.Explain local
variable declarations with an end-line comment.

使用行尾注释解释局部变量声明。

63.Establish
and use a set of keywords to flag unresolved issues.

建立并使用一套关键字来标记
未确定的情况。

64.Label closing braces in highly nested control
structures.

在嵌套程度高的控制结构中标记结束。

65.Add a "fall-through"
comment between two case labels, if no break statement separates those
labels.

在两个case标签中，如果没有break语句分隔这些标签，加入“fall-through”注释。

66.Label
empty statements.

标记空语句。

Programming Convertions
编码约定

67.Consider declaring classes representing
fundamental data types as final.

考虑将表示基本数据的类声明为final。

68.Build concrete types from native types and other concrete types.

从本地类型和其它具体类型构建具体类型。

69.Define small classed and small methods.

定义更小的类和方法。

70.Define subclasses so they may be used anywhere
their superclasses may be used.

定义子类使之可以在父类使用的任何地方使用。

71.Make all fields private.

使所有成员变量私有。

72.Use polymorphism
instead of instanceof.

使用多态来替代instanceof。

Type
Safety类型安全

73.Wrap general-purpose classes that
operate on java
.lang.Object
to provide static type checking.

以操作java
.lang.Object
来包装通用类，提供静态类型检查。

74.Encapsulate enumerations as classes.

以
类的形式封装枚举型。

Statements and Expressions 表达式

75.Replace
repeated nontrivial e­xpressions with equivalent methods.

使用相当的方法来
替换重复出现的、有点复杂的表达式。

76.Use block statements instead of
e­xpression statements in control flow constructs.

使用块状语句来替代控制流结构的表
达式。

77.Clarify the order of operations with parentheses.

使
用括号来明确运算顺序。

78.Always code a break statement in the last case
of a switch statement.

在switch语句最后一个case中总是键入break语句。

79.Use
equals(), not ==, to test for equality of objects.

使用equals()而不是==
来测试对象的相等性。

80.Always construct objects in a valid state.

总
是构建状态有效的对象。

Construction 构造函数

81.Do
not call nonfinal methods from within a constructor.

不要在构造函数中调用非
final方法。

82.Use nested constructors to eliminate redundant
code.

使用嵌套构造函数来消除冗余代码。

Exception Handling异常处理

83.Use
unchecked, run-time exceptions to report serious unexpected errors that
may indicate an error in the program's logic.

使用不需检查运行时异常来报告严重的、无法
预期的错误，这可能指出程序逻辑中的错误。

84.Use checked exceptions to report errors
that may occur, however rarely, under normal program operation.

使用
需检查异常来报告可能发生但是在正常程序操作中很难发生的错误。

85.Use return codes to report
expected state change.

使用return代码来报告期望的状态改变。

86.Only
convert exceptions to add information.

仅以增加信息形式来改变异常。

87.Do
not silently absorb a run-time or error exception.

不要略去运行时或错误异常。

88.Use
a finally block to release resources.

使用finally块以释放资源。


Assertions 断言

89.Program by contract.

编程遵守约定。

90.Use
dead code elimination to implement assertions.

使用无效代码清除策略实现断言。

91.Use
assertions to catch logic errors in your code.

使用断言捕获代码中的逻辑错误。

92.Use
assertions to test pre- and postconditions of a method.

使用断言测试方法的前
置和后置条件。

Concurrency 并发

93.Use threads
only where appropriate.

仅在适当时使用线程。

Synchronization
同步

94.Avoid synchronization.

避免同步。

95.Use
synchronized wrappers to provide synchronized interfaces.

使用同步包装来提
供同步接口。

96.Do not synchronize an entire method if the method
contains significant operations that do not need synchronization.

如
果方法包含几个不需要同步的重要步骤，那么不要同步整个方法。

97.Avoid unnecessary
synchronization when reading or writing instance variables.

当读写实例变量
时避免不必要的同步。

98.Consider using notify() instead of notifyAll().

考
虑用notify()替代notifyAll()。

99.Use the double-check pattern for
synchronized initialization.

对于同步的初始化应使用双重检查模式。


Efficiency 效率

100.Use lazy initialization.

使用延迟初始化。

101.Avoid creating unnecessary objects.

避免创建不必要的对
象。

102.Reintialize and reuse objects to avoid new object
construction.

重复初始化和重复使用对象以避免创建新的对象。

103.Leave
optimization for last.

留待以后优化。

Packaging Conventions
包约定

104.Place types that are commonly used, changed,
and released together, or mutually dependent on each other, into the
same package.

把经常使用、变化和发布或者彼此互相依赖的的类放置在相同的包中。

105.Isolate
volatile classes and interfaces in separate packages.

将volatile类和接口隔离在单独的包中。

106.Avoid making packages that are
difficult to change dependent on packages that are easy to change.

避免创建的包，依赖于经常变化的包，使其很难变化。

107.Maximize abstraction to maximize
stability.

最大的抽象化以达到最大的稳定性。

108.Capture high-level design
and architecture as stable abstractions organized into stable package.

采用高水平的设计和架构使包保持稳定。