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

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 expressions with equivalent methods.
使用相当的方法来替换重复出现的、有点复杂的表达式。

76.Use block statements instead of expression 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.
采用高水平的设计和架构使包保持稳定。