Java编程规范

1、工程管理系统工程规划一般地，开发一个产品或项目时，需要对整个应用程序有一个整体上的或者说全局上的规划。比如，层次划分和模块化。按分层进行组织的设计结构中，只允许上层的程序引用下层的程序，而不允许出现下层的程序引用上层的程序，依赖关系要做到单向化（偏序依赖）。另 一个概念模块化，主要是指把程序组织成多个逻辑概念相对独立的单元，便于维护和管理。这些单元在物理上的体现主要是程序工程（也有叫作项目的，英文表示是 Project）。单元的划分要遵从高内聚低耦合的原则进行。单元之间的依赖关系也必须是单向的，并且不与系统整体上的层次关系产生冲突。以上内容主要在开发周期中的设计阶段完成，还有一些其它内容，概括

2、起来，需要明确的主要有以下一些内容：· 系统的层次结构及工程存放目录组织· 构成系统的所有工程的清单，包括各工程的类型、所处位置、内容与其它说明等· 工程之间的依赖关系图，包括依赖的第三方组件· 依赖的第三方组件或类库的清单，包括名称、版本、官方网站地址、其所依赖的其它组件和类库，以及详细的修改记录（如果有修改的话）工程与配置管理Java 各类工程（Project）都包含特定的内容，依工程类型（最常见的有类库、控制台程序和 WEB 应用程序三类）不同，内容也会有不同，但一些基本内容是都有的，比如工程文件、Java 源程序文件、二进制输出目录等。我 们利用

3、配置库来达到统一管理和相互协作的目的。但 Java 工程中，并不是所有的内容都需要或者说适合纳入配置库，比如说二进制输出目录，它们只是一些临时生成的数据或文件，并不需要持久保留，还有一些文件是用户 使用的 IDE 或构建工具存储的特定文件等，同样不应该签入配置库。配置库处理原则是，只把需要及合适的内容签入配置库，其它内容一律不入库，以避免不必要的“垃圾”内容和对他人的干扰。Java 工程中可能出现的，一定不要签入配置库的目录及文件，包括但不限于以下所列：· maven 相关o target/· Eclipse 相关o bin/o .settings/o .projecto

4、.classpath· IDEA 相关o .idea/o *.ipro *.imlo *.iws· 临时性文件o *.logo *.cacheo *.diffo *.patcho *.tmp· 系统相关o .DS_Storeo Thumbs.db代码风格命名风格在使用 Java 语言编程的时候，尽量坚持以下的原则进行命名：1. 名称尽量要直接表明其含义，并且要使用英文单词表述，尽量避免使用汉语拼音命名。名字的意思清楚比长度更重要，应该与场景、系统的逻辑组成或物理组成以及为人熟知的概念相对应，而不是与技术或架构相对应；2. 除一些约定俗成的单字母变量（如 i, j,

5、 k, v, x, y 等），禁止使用单字母变量。在使用单字母变量时，也仅限于表示约定的含义，如 i, j, k 表示循环；v 表示取值；x, y 表示两个操作数；3. 命名时可以适当使用单词缩写，但一定要含义明确，如 exec；4. 在命名的过程中要使用语义上有意义的名字，而不要使用编程语言特有的关键字。如：getLength() 比 getInt() 要好得多；5. 类命名尽量使用名词性短语，如：FileCreator, HotelListManager, TaskWorker 等。6. 方 法命名一律以小写字母开头，命名时尽量不超过 3 个单词，第一个单词后的每个单词首字母需要大写。执行

6、操作命令类型的方法命名时一般用动词或动词短语命名，如 Executor.execute() 等；执行转化命令类型的函数命名时一般用 toXxx(), parseXxx(), valueOf() 的形式命名，如：Object.toString(), Integer.parseInt(), Enum.valueOf()；7. 类成员的命名尽量避免再使用类名（包括缩写形式）做前缀，例如 User.getUserId() 命名为 User.getId() 更加合适;8. 避免使用 Java 预定义的类型名称命名自己的类型。代码组织包尽 量将功能相近或同属一个性质的类型放在同一包中（同属一个性质特指 u

7、til 或类似的包，并不是指 controller, service, model 等），这样在开发的时候，就可以避免导入过多的包，且减少查找适用于特定任务的正确类型时所必须检查的包的数量，也可以避免不相干内容之间的相互干扰。从 一定程度上来说，就是包级别的高内聚、低耦合。类Java 的类型分为引用类型和值类型两类（正因为有值类型的存在，所以 Java 并不是纯面向对象的语言）。除 Java 预定义的 8 个基本类型是值类型之外，其它所有类型都是引用类型。引用类型在堆中分配，内存管理由垃圾回收器处理。值类型在栈上或以内联方式在堆中分配。通常，值类型 的内存分配和释放开销更小，所以，只要能够采用

8、值类型的地方，应优先考虑值类型（只有当值类型遇上 Java 5 引入的泛型时，才适合使用其相对应的包装类型）。然而，如果是在有大量的装箱或拆箱操作的情况下，值类型的表现就不如引用类型了。以下规则中，不严格区分类、接口或枚举等概念，统称为类。1. 类名与文件名应该保持一致；2. 类声明必须处在某个包中，禁止在缺省包中声明类；3. 在一个类文件中，除内部类之外，应该尽量只定义一个类，建议避免在一个文件中定义多个类。合适的情况下，可以考虑定义为内部类，且优先选择静态嵌套类；4. 只在需要公开给其他人使用的类前加上 public 关键字，内部使用的类使用访问级别更低的关键字来修饰；5. 不需要再被继承

9、的类前加 final 关键字；6. 设计上一旦初始化便不打算再被改变的内容，一律用 final 关键字修饰。接口与狭义上的类相比，接口具有其自身的独特属性，以下规则有助于正确设计接口：1. 除公开API, 应优先考虑定义类，而不是接口。因为在以后的版本调整中，可以安全地向类添加新成员，而对于接口，则只有修改很多代码（可能有多个类实现了接口）才能添加成员，影响面很宽；2. 接口中定义每一个方法时要合理地设计会抛出的异常；3. 避免使用标记接口（没有成员的接口），可以使用自定义属性（Annotation）作为类型标记的方式；4. 请提供至少一种接口实现的类型，这样有助于确保正确设计和顺利实现接口；

10、5. 尽量不要向以前提供的接口添加成员，如果接口的交付定义要求更多成员，则可以考虑定义新的接口扩展已有接口并添加适当成员。枚举枚举一般用于表示一组具有特定取值范围的常量，所以其所有属性都必须是不可变的，枚举的定义中不能提供任何可以修改其任何状态的途径。Java 的枚举在本质上是类，属于引用类型，可以考虑充分利用其多态特性。1. 一定要为枚举提供一个“零”值。通常情况下，“零”值项被命名为 None、Unknown 或 Invalid 是合适的。如果不合适，请根据具体情况把“零”值定义为最合适的项（一般是用作默认值的项）；2. 构造函数必须是私有的；3. 所有字段都必须是 final 的。字段字

11、段用于保存状态数据。实例字段用于存储对象的状态；静态字段用于表示某个共享状态，特殊的，常量（或不可变字段）适合表示一些固定值或不变数据。在绝大多数情况下，类的所有的实例字段都应是对外不可见的；而静态字段应尽量是常量（或不可变字段）。下面的规则有助于正确设计和使用字段：1. 不提供在实际上是公共访问级别的实例字段和可变的静态字段；2. 对不会更改的常量（或不可变数据）使用常量字段（static final）。方法1. 尽量避免写出超过 50 行的方法；2. 类应该只对外公布必需的方法，尽可能的隐藏内部实现，在声明方法时应该合理的考虑 private、protected、default 等可见级别

12、。参数与返回值1. 实际上对外可见的方法的参数和返回值类型应使用接口，而不是某一个具体的实现类。如：使用 List, Map 会比使用 ArrayList, HashMap 更合适；2. 参数的个数建议不超过 6 个。当多于 6 个时，应考虑是否把一部分或全部参数包装成一个具有特定含义的对象更合适；3. 一定要验证实际上对外可见的方法的参数，如果验证失败会导致抛出异常，则应该在方法注释中说明在何种情况下会抛出何种异常；4. 如果调用方几乎总要将输入放入数组，则不要使用 varargs 形式的参数。局部（本地）变量1. 尽量在第一次使用局部变量的前一行进行声明（使用时声明）；2. 保证局部变量有

13、最小的作用域（作用域最小化）；3. 每一个局部变量，只行使单一的职责，尽量避免一个局部变量，连续承载不同含义的数据。语句1. 一行只写一条语句，不允许把多条语句（即使很短）写在一行中；2. 尽量避免写过长的代码行（为了避免还要动用左右滚动条才能看到一行代码的完整内容）；3. 尽量避免编写连续的对象调用的语句（如 map.get(key).doXxx() ），如果需要在对象上获取对象后继续操作，要确保或检查对象不是空引用，以避免产生空指针异常；4. 尽量避免编写整合的自增/减操作。注释Java 中的注释主要有两类，一类是文档注释，另一类是代码注释。文档注释指的是程序对外公开的所有内容的使用说明或

14、功能描述及相关细节阐述，也可以被叫作 API 注释。代码注释主要是指文档注释之外的用于说明代码执行原理或所表示的信息等内容的相关说明，一般出现在局部（字段上的说明，或方法内部的说明等）。两类 注释的最大区别在于，文档注释可用于生成程序的 API 说明文档，可以脱离源代码独立使用；而代码注释只对特定的源代码进行必要的说明，一般只出现在源程序代码中，不单独出现。 更新代码时要保持注释同步更新。 文档注释文档注释的语法结构支持多行注释内容，起始标记为 "/*", 结束标记为 "/" （均不含引号）。注释内容与起始标记以及注释内容和结束标记间

15、都保留一个空格，所有的注释行上下相连，中间不穿插其它内容，且整个注释内容直接出现在被注 释元素之上，注释与被注释的元素之间也不穿插其它内容（Java 5 引入的 Annotation 不算）。关于文档注释的编写，可参考 How to Write Doc Comments for the Javadoc Tool or Javadoc.代码注释1. 代码中应该适当增加注释，注释和空行都是程序代码的重要组成部分。注释要能够说明程序的含义和算法，简明扼要，但不要过多过滥；2. 注释的缩进要与代码对齐；3. 对注释要做严格地拼写检查，保证措辞、语法、标点符号都正确地使用，

16、保证语句通顺，易于理解，避免产生歧义或混乱；4. 一目了然的语句不加注释。格式给出代码格式的，请严格按照给定格式编写相关的代码。尤其是其中的花括号与空格，不能被省略或不写。换行符统一使用 Unix 换行符（'n'），不允许使用其它平台相关的换行符。字符编码统一使用 UTF-8, 不允许使用其它字符集。缩进与空行1. 缩进以4个英文半角空格字符为合适的宽度，严禁4个空格符宽度以外的缩进长度；2. 代码中应该在合适的位置留有空行，空行也是程序代码的重要组成部分，空行用于分隔代码内部的逻辑块，分割类的各个成员，以一行为佳；3. 在运算符和操作数之间保留一个空格（单目运算符可例外）。花

17、括号配对1. 左花括号（""）与代码块起始语句或关键词在同一行，且括号前保留一个空格；右花括号（""）独占一行，并和括号外的代码对齐；2. 花括号中只有一行代码的时候，也保留花括号。分支语句if-else/ only ifif (condition_expression) statements; / if-elseif (condition_expression) statements; else statements_otherwise; / multi-branch 1 if (condition_expression_1) statements_1

18、; elseif (condition_expression_2) statements_2; elseif (condition_expression_n) statements_n; else / optional statements_otherwise; / multi-branch 2 if (condition_expression_1) statements_1; return result_1; if (condition_expression_2) statements_2; return result_2; if (condition_expression_3) state

19、ments_3; return result_3; statements_otherwise; return result_otherwise; 在多路转移（multi-branch）中，应该把出现几率越高的条件分支排得越靠前。 switch/ 其中的 enum 不只是指 Java 中的 enum 类型，而是逻辑概念上的一组可枚举的值。 switch (enum_variable) case enum_value_1: statements_1; break; case enum_value_2: statements_2; break; case enum_value_n

20、: statements_n; break; default: statements_otherwise; break; switch (enum_variable) case enum_value_1: statements_1; break; case enum_value_2: statements_2; break; case enum_value_n: statements_n; break; default: statements_otherwise; break; switch (enum_variable) case enum_value_1: statements_1; re

21、turn result_1; case enum_value_2: statements_2; return result_2; case enum_value_n: statements_n; return result_n; default: statements_otherwise; return result_otherwise; switch (enum_variable) case enum_value_1: statements_1; return result_1; case enum_value_2: statements_2; return result_2; case e

22、num_value_n: statements_n; return result_n; default: statements_otherwise; return result_otherwise;  - 任何情况下，switch 语句中的 default 分支都不能被省掉，而且要出现在所有分支的最后；- 其它 case 分支按出现几率从大到小自上而下地依次排列。 循环语句for/ c 表示集合和数组 / c.size() 表示 c 中元素的个数 for (int i = 0; i < c.size(); i+) / 如果性能敏感，可考虑 for (int i = 0

23、, count = c.size(); i < count; +i) statements_handling_ci; for (int i = c.size() - 1; i >= 0; i-) statements_handling_ci; for (T t : c) statements_handling_t; while 和 do-whilewhile (condition_expression) statements; do statements; while (condition_expression);其它常用语句try-catch-finallytry stateme

24、nts; / 可能抛出异常 XxxException catch (XxxException e) statements_handling_e; / 处理异常的语句，一般不能为空（什么都不写），也不能只是 throw e，也不能是 e.printStackTrace(); finally / 可选，视情况而定 statements; / 处理资源回收等事宜 / catch 块与 finally 块根据实际情况不一定会都有，但 catch 和 finally 至少会有一个。synchronizedsynchronized (instance_of_reference_type) statemen

25、ts;  instance_of_reference_type 是一个引用类型的实例，推荐使用 java.lang.Object 类的实例。这里 instance_of_reference_type 一定不能是字符串、类型实例（由 类.class 获取到的值）、类似于类型实例的会用于程序全局的单实例对象，以及在使用过程中会发生对象切换的变量等。synchronized (this) 是一种不推荐的做法，应该尽量避免，除非总是希望内部代码与外部使用程序阻塞到一块儿去。 代码设计原则可见性与密封性在面向对象技术出现之前，对数据的封装理念就已经很流行。面向对象技术又把这一理念推向

26、了更高的高度。可见性与密封性就是封装概念中涉及到的两个十分重要的概念。可见性在 Java 中被叫做“可访问级别”。Java 提供了四个不同级别的可访问性，分别是 private, default, protected, public.良 好的编程实践，都会特别注意代码的可见性，为不同的内容指定相应的可访问级别。我们需要坚持的规则是，良好的设计代码，公开的 API 使用合适的公开访问级别，实现代码及其它内容尽量封装在包内部，使其对外不可见，优先考虑 private, 如果需要包内可见，则应考虑 default. 选择的依据是可见性要尽量的低，公开的内容越少，对外的责任就越小，模块之间的耦合度也就

27、越小。而需要对外公开的内容，则需要花大力气好好捉摸清楚，尽量 保证接口的稳定性、含义准确性、逻辑完整性及一致性。密封性是面向对象代码封装理论中另一个重要的概念。主要是指对程序扩展者修改或扩展原程序行为的限制。比如，把一个类做成密封的，则这个类就不可以再被扩展；把一个方法做成密封的，扩展类就不能重写这个方法。Java 提供密封性特点的关键字是 final.允许扩展（继承）只应该出现在程序特定的设计目的中，如果程序设计的目的中并没有考虑扩展性，则一律把相应的代码全做成密封的。方法参数的方向一般情况下，方法的参数都是“传入（in）”，方法的结果采用返回值（return）的方式。Java 不支持像 C

28、# 语言中的“传出（out）”参数的类似东西。方 法的设计，应尽最大努力避免导致修改方法的输入参数的状态的情况。比如，设计了一个方法，其传入参数是一个自定义类型的对象，输出是一个整数。那么如果想 返回多于一个整数的数据，在 Java 中就不好做到了。这时，有人会灵机一动，通过“传入”的对象的某个字段把想要的内容带出去。这里想说的就是，方法的设计要尽最大努力避免这种情况的出现。 这种情况，可考虑方法的返回值使用一个具有良好定义的对象。特殊地，有一类函数，是为了向数组或集合中装填数据或重排其中元素的顺序，又或者是对其中的数据进行过滤，而数组或集合的实例是由函数的调用者传递过来的，这种情况下，函数的

29、实现向传入的数组或集合中追加数据，重排其中元素的顺序，或对其中的数据进行过滤的设计是合适的。常量 这里所说的常量，是一种狭义上的常量，特指由 static final 修饰的基本类型（Java 共定义了 8 种基本类型）的变量。 需要特别注意的一点是“公开的（可访问级别为 public 以及 protected 的，概括起来，就是可被本程序集外的程序访问的）”常量的定义需要十分的谨慎。对于“非公开的”常量，我们鼓励使用。但对于“公开的”常量，情况要复杂得多，而这一点往往会被忽略（或无视）。被定义为“公开的”常量需要有以下几个必需的特点：1. 定义出来的常量永远不会被去掉；2

30、. 定义出来的常量永远不会被修改；3. 定义出来的常量的含义永远不会发生变化。如果一个“常量”不具备以上所有特点，则不应该定义成“公开的”。只读与状态状态由数据来体现，而数据在 Java 中主要是通过“变量”来存储的。Java 的变量允许被定义为“只读的”，只读的变量的值在运行时除初始化外是不允许被修改的（编译器保证）。一般地，如果一个对象没有任何数据（字段），则我们说这个对象是“无状态的”。如果一个对象的数据在任何情况下都不会发生改变，则我们说这个对象是“状态不可变的”。无状态对象可视为状态不可变对象的一个特例。状态不可变对象可安全地用于多线程环境，不会出现数据错误及混乱问题。如果一个对象的

31、状态是可变的，又需要用于多线程环境，那么对这个对象的访问就需要做同步控制（Java 提供的锁机制，或程序开发者自己实现的控制策略等）。在“单实例”或“多实例”模式中，请优先考虑把对象做成“无状态的”或“状态不可变的”。一 般地，“无状态对象”与“静态类”之间最大的区别在于，“无状态对象”可以实现接口，方便做集成，也方便隐藏自己的实现类；而“静态类”更多地用于定义一 些通用性的“工具”。如果需要实现特定的接口，肯定是选择定义成无状态对象；如果要提供的功能更像是一些通用性的“工具”，则应该优先考虑定义成“静态 类”；其它情况则应视具体情况而定，如果不需要实现特定接口，而又考虑性能问题，则推荐优先考

32、虑“静态类”。静态变量不推荐使用。如果确实有需要，则应优先考虑定义为“只读的”。如果是引用类型的，则还应该尽量是“状态不可变的”对象。如果不是只读的不可变的数据，则要么保证其处在单线程环境中，要么保证对其的访问做了“同步控制”。这些控制统一应该由变量定义者来保证，而不是变量使用者。静态方法推荐使用。只要是能定义成静态的方法，就尽量定义成静态的。静态类推荐使用。合理使用异常1. 用抛出异常代替返回错误代码（错误码适合系统间调用）；2. 不要在不恰当的场合下引发异常，不要对正常控制流使用异常。除了系统故障及可能导致争用状态的操作之外，框架设计人员还应设计一些 API 以便用户可以编写不引发异常的代

33、码。可以提供一种在调用成员之前检查前提条件的方法，以便用户可以编写不引发异常的代码；3. 不要根据某一选项的值来确定引发或不引发异常；4. 重新引发异常时使用 Inner Exception (cause)；5. 要捕捉特定的异常，而不是一般的异常；6. 避免嵌套捕捉异常；7. 避免“吃掉”异常，即捕捉了异常却什么也不做；8. 避免无用的异常捕获，即捕捉到异常后，只是把异常又抛了出去，其它什么都没做，这是不应该出现的做法；9. 对于可能引发异常的成员，可以考虑使用 Tester-Doer 模式来避免与异常相关的性能问题；10. 总是处理未捕获的异常，这个是对于整个系统或者某个独立的特定的模块来

34、说的，而不是针对一个方法或函数；11. 避免在 finally 内编写无效代码；12. 方法在何种情况下会抛出何种异常也是方法对外“接口”的一部分。字符集问题Java 支持多语言和多种字符编码。使用 Java 处理字符或字符串，请遵循以下原则：1. 不使用缺省字符集（编码）；2. 不使用 Java 提供的任何使用缺省字符集（编码）的接口、类或方法；3. 显示指明使用的字符集（编码），优先考虑 UTF-8；4. 系统对接程序需要协商使用的字符集（编码），且显式指明使用的字符集（编码），优先考虑 UTF-8.合理注释本节所说的注释一律指文档注释。注释的必要性程 序对外提供的接口（广义的接口含义，指

35、程序向外公开的所有内容）表明了其对外所做的承诺，承诺一旦做出，就不能再轻易或随便修改。文档注释就相当于是这份 承诺的契约，所以文档注释应准确的描述程序对外的所有承诺（涉及承诺的任何一个细节），不能出现含糊不清或模棱两可的内容，且一经发布便不能再轻易的修 改。程序提供者应为做出的承诺负全责。如果承诺被修改了（契约肯定也要做相应的修改），则修改者应为因此而导致的所有后果负责，并为新改出来的承诺负全 责。· 必须添加注释的元素简单的说就是程序对外公开的所有内容。反映在 Java 中，主要是指那些被 public 以及 protected 所修饰的内容。· 建议添加注释的元素必须添加注释的元素之外的其它元素，比如 default 的和 private 的，也应该尽量添加注释，以说明内部 API 的设计承诺，方便后期维护。注释成分的最小集上 一小节中指出，文档注释是对程序向外所做承诺的完整而准确的描述，所以应