java编码规范

1. 介绍

为统一公司Java项目编码规范，提高可读性，特制定本规范。

本规范同样适用于Android项目。

本规范基于Google Java Style，主要的区别如下：

• 保留了百度原有规范的4空格缩进和120字符列宽限制

• 放松了对import语句的组织方式要求。只要有一定逻辑性即可，不做严格限制。但要求未使用的import语句必须删除

• 对Android的成员变量命名允许了例外。

  • 非public非static的变量可以使用m开头
  • 非常量的static变量可以使用s开头

• switch语句禁止了case贯穿，同时要求default必须被终止。

• 允许特殊场景下的单字符参数命名，例如使用x、y表示坐标。

• 禁用了枚举类的单行风格

  private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
  

• 禁用了无参数注解的不换行风格

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

  @Partial @Mock DataLoader loader;
  

• 增加了对使用拼音命名的说明：不建议但允许少量例外。

• 禁止使用连续的空行进行分隔。

• 禁用了一种数组初始化换行的风格。

  new int[]
      {0, 1, 2, 3}
  

• 禁止使用连续的空格分隔。不再允许使用增加空格来进行对齐的风格。

• 允许包名中包含数字，例如 org.apache.logging.log4j

• JavaDoc允许多种形式的段落分隔方式

相对于原先的百度Java编码规范，本规范做出了大量更加严格的限制，但是7、8、9三节的有关编程实践的规定基本取消。部门可根据自己需要对规范进行加强。

1.1. 术语

除非特别约定，我们使用以下术语：

• 类用于指代所有类（class）、枚举（enum class）、接口（interface）以及注解（annotation）。
• 注释仅用于指代行间注释，Javadoc用于指代文档注释。

1.2. 文档说明

本文中所使用的示例代码不具备唯一权威性。示例代码只代表一种符合规范的写法，也可能存在其他符合规范的不同写法。

2. 源文件规范

2.1. 文件名

源文件名必须和它包含的顶层类名保持一致，包括大小写，并以.java作为后缀名。

2.2. 文件编码

所有源文件编码必须是UTF-8

2.3. 特殊字符

2.3.1. 空格

除了换行符之外，ASCII空格（0x20）是唯一合法的空格字符。这意味着

• 所有在源代码中（包括字符、字符串以及注释中）出现的其他空格字符需要转义,例如Tab用\t表示。
• 缩进必须使用空格而不是Tab

2.3.2. 特殊转义字符

对于有特殊转义表示的字符（\b, \t, \n, \f, \r, \", \', \\），禁止使用其它等价转义方式。例如\012或者\u00a表示。

2.3.3. 非ASCII字符

对于非ASCII字符，可以使用实际字符（如∞）或者它的Unicode转义（如\u221e），取决于哪种写法的可读性更好。

使用注释有助于增强可读性

示例：

Example	Discussion
String unitAbbrev = "μs";	最佳写法，无需注释就可以理解
String unitAbbrev = "\u03bcs"; // "μs"	虽然合法但是很没有必要的写法
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	虽然合法但是很难理解的写法
String unitAbbrev = "\u03bcs";	让人完全读不懂的写法
return '\ufeff' + content; // byte order mark	很好的写法，用Unicode转义来表示非打印字符，并且有合适的注释帮助阅读者理解

3. 源文件组织结构

源文件必须按顺序由以下部分组成：

1. 许可证（License）或版权声明（Copyright）
2. package语句
3. import语句
4. 唯一的顶层类

每两部分之间用一个空行分隔

3.1. 许可证（License）或版权声明（Copyright）

如果文件有许可证（License）或版权声明（Copyright），放在最开头。如果没有的话，此部分可以忽略。

3.2. package语句

package语句占据单独一行不换行，允许超出120字符列宽限制。

3.3. import语句

3.3.1. 禁止通配符import

无论是static还是非staic imports，均禁止使用通配符import。

3.3.2. 不换行

每条import语句占据单独一行不换行，允许超出120字符列宽限制。

3.3.3. 顺序

import语句需按照一定的逻辑顺序组织。

可参考以下的组织形式，不强制：

按以下顺序进行分组，每两组之间用一个空行分隔。

1. 所有的static import语句

2. com.baidu import语句（仅当源文件属于com.baidu时适用）

3. 第三方包。每个顶层包独立一组，按ASCII顺序排列

   例如：android, com, junit, org, sun

   <