Java编程风格

Java编程的风格介绍，主要参考乐google的java code style。对模糊部分作出了明确的选择。

源文件基础

1.1 文件名

源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java。

1.2 文件编码：UTF-8

源文件编码格式为UTF-8。

1.3 特殊字符

1.3.1 空白字符

除了行结束符序列（这里指源码的换行），ASCII水平空格字符（ 0x20，即 空格 ）是源文件中唯一允许出现的空白字符，这意味着：

1. 所有其它字符串中的空白字符都要进行转义。
2. 制表符不用于缩进。

1.3.2 特殊转义序列

对于具有特殊转义序列的任何字符（ \b, \t, \n, \f, \r, \“, \‘及\ ），我们使用它的转义序列，而不是相应的八进制（比如 \012）或Unicode（比如 \u000a）转义。

1.3.3 非ASCII字符

对于剩余的非ASCII字符，是使用实际的Unicode字符（比如 ∞ ），还是使用等价的Unicode转义符（比如 \u221e），取决于哪个能让代码更易于阅读和理解。

Tip: 在使用Unicode转义符或是一些实际的Unicode字符时，建议做些注释给出解释，这有助于别人阅读和理解。

例如：

Tip: 永远不要由于害怕某些程序可能无法正确处理非ASCII字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时，它自然无法正确运行， 你就会去fix这些问题的了。 如果真的有需要的话，大胆去用非ASCII字符。）

源文件结构

一个源文件按顺序包含以下内容：

1. 如有需要，头部要有许可证或版权信息。
2. package声明语句
3. import引用语句
4. 仅有一个顶级类

以上每个部分之间必须用一个空行隔开。

2.1 许可证或版权信息

如果一个文件包含许可证或版权信息，那么它应当被放在文件最前面。

2.2 package语句

package语句不换行，必须写在一行里。3.4节的列限制并不适用于package语句。 包名必须使用com.anteam开头，加部门名称和项目名称。

例如： com.anteam.hrs.cache、 com.anteam.hrs.ws、 com.anteam.hrsp.talk等。

2.3 import语句

2.3.1 import不要使用通配符

不要出现类似这样的import语句：import java.util.*;

2.3.2 不要换行

import语句不换行，需要写在一行里，4.4节的列限制并不适用于import语句。

2.3.3 顺序和间距

import语句可分为以下几组，按照这个顺序，每组用一个空行分隔：

1. 所有的静态导入独立成组
2. com.anteam imports，仅当这个源文件是在com.anteam包下。
3. 第三方的包，每个顶级包为一组，按照ASCII字典排序。
   • 例如：android, com, junit, org, sun
4. java imports
5. javax imports

组内不空行，按字典序排列。

2.4 类声明

2.4.1 只有一个顶级类声明

每个顶级类都在一个与它同名的源文件中。

例外：package-info.java，该文件中可没有package-info类。

2.4.2 类成员顺序

类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。 最重要的一点，每个类应该以某种逻辑去排序它的成员，维护者应该要能解释这种排序逻辑。 比如， 新的方法不能总是习惯性地添加到类的结尾，因为这样就是按时间顺序而非某种逻辑来排序的。

一个类的成员按顺序包含以下内容：

1. 类变量。
2. 对象成员变量。
3. 构造方法。
4. 类方法。
5. 实现接口的方法。
6. 重写父类的方法（此处包含覆盖Object的toString\equals等方法）。
7. 抽象方法。
8. 对象的工具方法。
9. 属性的Getter/Setter

2.4.2.1 重载：永不分离

当一个类有多个构造函数，或是多个同名方法，这些函数/方法应该按顺序出现在一起，中间不要放进其它函数/方法。

格式

术语说明：块状结构(block-like construct)指的是一个类，方法或构造函数的主体。 需要注意的是，数组初始化中的初始值可被选择性地视为块状结构（ 3.8.3.1节 ）。

3.1 大括号

3.1.1 使用大括号

大括号与if, else, for, do, while语句一起使用，即使是空代码段或者只有一条语句，也应该把大括号写上。

3.1.2 非空块：K & R 风格

对于非空块和块状结构，大括号遵循Kernighan和Ritchie风格 （Egyptian brackets）:

• 左大括号前不换行
• 左大括号后换行
• 右大括号前换行
• 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行。例如，如果右大括号后面是else或逗号，则不换行。

示例：

return new MyClass() {
    @Override public void method() {
        if (condition()) {
            try {
                something();
            } catch (ProblemException e) {
                recover();
            }
        }
    }
};

3.1.3 空块：可以用简洁版本

一个空的块状结构里什么也不包含，大括号可以简洁地写成{}，不需要换行。但如果它是一个多块语句的一部分（ if/else 或 try/catch/finally ） ，即使大括号内没内容，右大括号也要换行。

示例：

void doNothing() {}

3.2 块缩进：4个空格

每当开始一个新的块，缩进增加4个空格，当块结束时，缩进返回先前的缩进级别。缩进级别适用于代码和注释。（见3.1.2节中的代码示例）

3.3 一行一个语句

每个语句后要换行。

3.4 列限制：100

一行100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行。

例外：

• 不可能满足列限制的行(例如，Javadoc中的一个长URL，或是一个长的JSNI方法参考)。
• package和import语句（见2.2节和2.3节）。
• 注释中那些可能被剪切并粘贴到shell中的命令行。

3.5 自动换行

术语说明：一般情况下，一行长代码为了避免超出列限制（100个字符）而被分为多行，我们称之为自动换行（line-wrapping）。 这里并没有全面的准则来决定在每一种情况下如何自动换行。很多时候，对于同一段代码会有好几种有效的自动换行方式。

Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题。

3.5.1 从哪里断开

自动换行的基本准则是：更倾向于在更高的语法级别处断开。

1. 如果在非赋值运算符处断开，那么在该符号前断开（比如+，它将位于下一行）。
   • 这条规则也适用于以下“类运算符”符号：点分隔符（ . ），类型界限中的&（\），catch块中的管道符号（catch (FooException | BarException e)）
2. 如果在赋值运算符处断开，通常的做法是在该符号后断开（比如=，它与前面的内容留在同一行）。
   • 这条规则也适用于foreach语句中的分号（ : ）。
3. 方法名或构造函数名与左括号留在同一行。
4. 逗号（ , ）与其前面的内容留在同一行。

3.5.2 自动换行时缩进至少+4个空格

自动换行时，第一行后的每一行至少比第一行多缩进4个空格（注意：制表符不用于缩进。见1.3.1节）。

当存在连续自动换行时，缩进可能会多缩进不只4个空格（语法元素存在多级时）。两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。

第3.6.3水平对齐一节中指出，不鼓励使用可变数目的空格来对齐前面行的符号。

3.6 空白

3.6.1 垂直空白

以下情况需要使用一个空行：

• 类内连续的成员之间：字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块。
  • 例外：两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组。
• 在函数体内，语句的逻辑分组间使用空行。
• 要满足本文档中其他节的空行要求(比如2.3节：import语句)
• 类内的第一个成员前或最后一个成员后的空行是可选的（既不鼓励也不反对这样做，视个人喜好而定）。
• 多个连续的空行是不允许的。

3.6.2 水平空白

除了语言需求和其它规则，并且除了文字、注释和Javadoc用到单个空格，单个ASCII空格也出现在以下几个地方：

1. 分隔任何保留字与紧随其后的左括号（ ( ）（ 如if, for catch等）。
2. 分隔任何保留字与其前面的右大括号（ } ）（ 如else, catch ）。
3. 在任何左大括号前（ { ），有两个例外：
   • @SomeAnnotation({a, b})（不使用空格）。
   • String[][] x = foo;(大括号间没有空格，见下面第8个条目)。
4. 在任何二元或三元运算符的两侧。这也适用于以下“类运算符”符号：
   • 类型界限中的&（ \ ）。
   • catch块中的管道符号（ catch (FooException | BarException e ）。
   • foreach语句中的分号（ : ）。
5. 在逗号（ , ）、冒号（ : ）、分号（ ; ）及右括号（ ) ）后
6. 如果在一条语句后用双斜杠（ // ）做注释，则双斜杠（ // ）两边都要空格。这里只要一个空格。
7. 类型和变量之间：List\ list。
8. 数组初始化中，大括号内的两侧空格，即byte[] bytes = { 5, 6 }。
   • 但空数组内不需要空格，即byte[] bytes = {}

Tip：这个规则并不要求或禁止一行的开关或结尾需要额外的空格，只对内部空格做要求。

3.6.3 水平对齐：不允许

术语说明：水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。

允许-未对齐的代码：使用一个空格作分隔

private int x; // this is fine
private Color color; // this too

不允许-对齐的代码：使用不固定数量的空格对齐上下文

private int   x;      // permitted, but future edits
private Color color;  // may leave it unaligned

Tip：对齐可增加代码可读性，但它为日后的维护带来问题。考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。 这可能导致原本很漂亮的对齐代码变得错位。很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐(比如程序员想保持这种水平对齐的风格)。 这就会让你做许多的无用功，增加了reviewer的工作并且可能导致更多的合并冲突。

3.7 用小括号来限定组：推荐

除非coder和reviewer都认为去掉分组小括号能让代码更易于阅读，否则我们不应该去掉分组小括号。 我们不能保证之后的coder和reviewer能记住整个Java运算符优先级表。

3.8 具体结构

3.8.1 枚举类

枚举常量间用逗号隔开，并且用一个换行隔开。对每个枚举变量要有文档说明。 由于枚举类也是一个类，因此所有适用于其它类的格式规则也适用于枚举类。

/**
 * Bytes 与 String的转换方式
 *
 * @author bash
 * @version V1.0
 * @since 2015-05-19 14:57
 */
public enum PkcBtSMode {
    /**
     * 直接转换
     * 加密：enString   = new String(enBytes);
     * 解密：deBytes = string
     * .getBytes()
     * Warning 禁止登录
     */
    RAW(1),
    /**
     * 默认使用UC处理, 不可改变
     */
    DEFAULT(1),
    /**
     * 通过Hex转换
     * enString = Hex.toHexString(enBytes)
     * enBytes = Hex.decode(enString)
     */
    HEX(2);
}

3.8.2 变量声明

3.8.2.1 每次只声明一个变量

不允许：不要使用组合声明，比如

int a, b;

允许：应该分开声明，比如

int a;
int b;

3.8.2.2 局部变量需要时才声明，并尽快进行初始化

不要在一个代码块的开头把局部变量一次性都声明了（这是c语言的做法），而是在第一次需要使用它时才声明。 局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化。

3.8.3 数组

3.8.3.1 数组初始化：可写成块状结构

数组初始化和普通的声明语句规则一直。需要注意的时大括号内侧的空格。

int[] nums = new int[] { 0, 1, 2, 3 };
int[] nums = { 0, 1, 2, 3 };

3.8.3.2 非C风格的数组声明

中括号是类型的一部分：String[] args， 而非String args[]。

3.8.4 switch语句

术语说明：switch块的大括号内是一个或多个语句组。每个语句组包含一个或多个switch标签（ case FOO:或default:），后面跟着一条或多条语句。

3.8.4.1 缩进

每个switch标签后新起一行，标签不锁进。标签内的语句缩进4个空格，写下一条或多条语句。其他格式与普通语句一致。

3.8.4.2 Fall-through：注释

在一个switch块内，每个语句组要么通过break, continue, return或throw来终止， 要么通过一条注释来说明程序将继续执行到下一个语句组， 任何能表达这个意思的注释都是OK的（典型的是用 //继续执行下一个Case）。 这个特殊的注释并不需要在最后一个语句组（一般是default）中出现。

示例：

switch (input) {
case 1:
case 2:
    prepareOneOrTwo();
    //继续执行下一个Case
case 3:
    handleOneTwoOrThree();
    break;
default:
    handleLargeNumber(input);
}

3.8.4.3 default的情况要写出来

每个switch语句都必须包含一个default语句组，即使它什么代码也不包含。

3.8.5 注解(Annotations)

注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行。这些换行不属于自动换行(第3.5节，自动换行)，因此缩进级别不变。

例如：

@RequestMapping(value = { "", "index" }, method = { RequestMethod.POST, RequestMethod.GET }, 
    headers = { "Accept=text/plain" })
@ResponseBody
@ResponseStatus(HttpStatus.OK)
public String indexPage(HttpServletRequest httpRequest) {
    return CommonRVCst.V_INDEX;
}

例外：单个的注解不可以和签名的第一行出现在同一行。以下情况时不允许的：

@Override public int hashCode() { ... }

应用于字段的注解紧随文档块出现，应用于字段的多个注解不允许与字段出现在同一行。例如：

@Partial @Mock DataLoader loader;

参数和局部变量注解和方法变量的规则同上。

3.8.6 注释

3.8.6.1 块注释风格

块注释与其周围的代码在同一缩进级别。它们可以是 /*…*/ 风格，也可以是 //… 风格。 对于多行的 /*…*/ 注释，后续行必须以星号（ * ）开始， 并且与前一行的星号（ * ）对齐。以下示例注释都是OK的。

/*
 * 这样是
 * 可以的
 */

// 这样也
// 可以

/* 你也可以
 * 这样 */

Tip：在写多行注释时，如果你希望在必要时能重新换行(即注释像段落风格一样)，那么使用/…\/。 双斜线（ // )一般用于注释一条语句。/*…*/用于注释一段代码块。

3.8.7 修饰符

类和成员的修饰符如果存在，则按Java语言规范中推荐的顺序出现。

public protected private abstract static final transient volatile synchronized native strictfp

命名约定

4.1 对所有标识符都通用的规则

标识符只能使用ASCII字母和数字，因此每个有效的标识符名称都能匹配正则表达式\w+。 在其它编程语言风格中使用的特殊前缀或后缀，如name_, mName, s_name和kName，在Java编程风格中都不再使用。

4.2 标识符类型的规则

4.2.1 包名

包名全部小写，连续的单词只是简单地连接起来，不使用下划线。

4.2.2 类名

类名、接口名、注解名都以UpperCamelCase风格编写。

• 类名通常是名词或名词短语。例如：Character、ImmutableList。
• 接口名通常是形容词或形容词短语。例如：Readable。
• 注解名目前没有特殊要求。
• 测试类的命名以它要测试的类的名称开始，以Test结束。例如，HashTest或HashIntegrationTest。

4.2.3 方法名

方法名都以lowerCamelCase风格编写。

方法名通常是动词或动词短语。

下划线不允许出现在类名、接口名和注解名中。

4.2.4 常量名

常量名命名模式为CONSTANT_CASE，全部字母大写，用下划线分隔单词。那，到底什么算是一个常量？

每个常量都是一个静态final字段，但不是所有静态final字段都是常量。在决定一个字段是否是一个常量时， 考虑它是否真的感觉像是一个常量。 例如，如果任何一个该实例的观测状态是可变的，则它几乎肯定不会是一个常量。 只是永远不打算改变对象一般是不够的，它要真的一直不变才能将它示为常量。

// 常量
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(',');  // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
static final String[] NON_EMPTY_ARRAY= { "these", "can", "change" };

// 非常量
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);

这些名字通常是名词或名词短语。

4.2.5 非常量字段名

非常量字段名以lowerCamelCase风格编写。 这些名字通常是名词或名词短语。例如：computedValues、index。

4.2.6 参数名

参数名以lowerCamelCase风格编写。

参数应该避免用单个字符命名。

4.2.7 局部变量名

局部变量名以lowerCamelCase风格编写，比起其它类型的名称，局部变量名可以有更为宽松的缩写。

虽然缩写更宽松，但还是要避免用单字符进行命名，除了临时变量和循环变量。

即使局部变量是final和不可改变的，也不应该把它示为常量，自然也不能用常量的规则去命名它。

4.2.8 类型变量名

类型变量可用以下两种风格之一进行命名：

• 单个的大写字母，后面可以跟一个数字（如：E, T, X, T2）。
• 以类命名方式（4.2.2节），后面加个大写的T （如：RequestT, FooBarT）。

4.3 驼峰式命名法(CamelCase)

驼峰式命名法分大驼峰式命名法（UpperCamelCase)和小驼峰式命名法(lowerCamelCase)。 有时，我们有不只一种合理的方式将一个英语词组转换成驼峰形式，如缩略语或特殊短语（例如”IPv6”或”iOS”）。 为了提高可预见性，指定以下的转换方案。

名字从描述语句开始:

1. 把短语转换为纯ASCII码，并且移除任何符号。例如：”Müller’s algorithm”将变成”Muellers algorithm”。
2. 把这个结果切分成单词，在空格或其它标点符号（通常是连字符）处分割开。
   • 推荐：如果某个单词已经有了常用的驼峰表示形式，按它的组成将它分割开(如”AdWords”将分割成”ad words”)。
   • 需要注意的是”iOS”并不是一个真正的驼峰表示形式，因此该推荐对它并不适用，iOS变为ios，Anteam变为anteam。
3. 现在所有字母都小写（包括缩写）的，将所有单次连接起来得到一个标识符。
   • 如果将每个单词的首字母都大写，可以得到大驼峰式命名。
   • 第一个单词首字母小写，其余单次首字母都大写，可以得到小驼峰式命名。

示例：

Tip：在英语中，某些带有连字符的单词形式不唯一。例如：”nonempty”和”non-empty”都是正确的，因此方法名checkNonempty和checkNonEmpty也都是正确的。

编程实践

5.1 @Override：必须加

只要是重写的方法，就把@Override注解给用上。

5.2 捕获的异常：不能忽视

catch异常必须作记录日志处理。然后做出其他操作，比如向上层抛出异常等等。 如果确实是不需要在catch块中做其他任何响应，需要做注释加以说明（如下面的例子，// 可以继续执行，不需要作其他处理 ）。

try {
    int i = Integer.parseInt(response);
    return handleNumericResponse(i);
} catch (NumberFormatException ok) {
    LOG.error("Int转换错误：" + response, e);
    // 可以继续执行，不需要作其他处理
}
return handleTextResponse(response);

5.3 静态成员：使用类进行调用

使用类名调用静态的类成员，而不是具体某个对象或表达式。

Foo aFoo = ...;
Foo.aStaticMethod(); // 赞成
aFoo.aStaticMethod(); // 不可以
somethingThatYieldsAFoo().aStaticMethod(); // 不可以

5.4 Finalizers: 禁用

不准重写Object.finalize。

Javadoc

6.1 格式

6.1.1 一般形式

Javadoc块的基本格式如下所示：

/**
 * 可失效的Talk
 *
 * @author bash
 * @version V1.0
 * @since 2015-10-22 09:28
 */
public interface HrspTalk extends Serializable {
    /**
     * 获取全部的attribute
     *
     * @return 一个Map。如果没有则返回EmptyMap
     */
    Map<String, Object> getAttributes();

    /**
     * 获取一个属性
     *
     * @param attributeName 属性名称
     * @param <T>           属性类型的泛型
     * @return 如果查到则返回该属性，否则返回null。
     * @throws ClassCastException 如果属性类型与目标类型不一致，则会抛出该异常。
     */
    <T> T getAttribute(String attributeName);
}

或者是以下单行形式：

/** An especially short bit of Javadoc. */

基本格式总是OK的。当整个Javadoc块能容纳于一行时，且没有Javadoc标记@XXX，可以使用单行形式。

6.1.2 段落

空行（只包含最左侧星号的行）会出现在段落之间和Javadoc标记(@XXX)之前（如果有的话）。 除了第一个段落，每个段落第一个单词前都有标签\，并且它和第一个单词间没有空格。

6.1.3 Javadoc标记

标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空。 当描述无法在一行中容纳，连续行需要至少再缩进4个空格。

6.2 摘要片段

每个类或成员的Javadoc以一个简短的摘要片段开始。这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中。

这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。它不会以{@code Foo}是一个…或方法返回开头, 它也不会是一个完整的祈使句，如保存记录…。

Tip：一个常见的错误是把简单的Javadoc写成/** @return 消费者ID */，这是不正确的。它应该写成/** 返回消费者ID. */。

6.3 哪里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc，以下是一些例外：

6.3.1 例外：不言自明的方法

对于简单明显的方法如getFoo，Javadoc是可选的（可以不写的）。这种情况下除了写“返回foo”，确实也没有什么值得写了。

单元测试类中的测试方法可能是不言自明的最常见例子了，我们通常可以从这些方法的描述性命名中知道它是干什么的，因此不需要额外的文档说明。

Tip：如果有一些相关信息是需要读者了解的，那么以上的例外不应作为忽视这些信息的理由。例如，对于方法名getCanonicalName， 就不应该忽视文档说明，因为读者很可能不知道词语canonical name指的是什么。

6.3.2 例外：重载

如果一个方法重载了超类中的方法，那么Javadoc并非必需的。

6.3.3 可选的Javadoc

对于包外不可见的类和方法，如有需要，也是要使用Javadoc的。如果一个注释是用来定义一个类，方法，字段的整体目的或行为， 那么这个注释应该写成Javadoc，这样更统一更友好。