java编程风格

1.术语

　　class

　　　　可表示一个普通类，枚举类，接口或是annotation类型( @interface)

　　comment

　　　　只用来指代实现的注释(implementation comments)，不使用“documentation comments”一词，而是用Javadoc

2.源文件基础

（1）文件名

　　　源文件以其最顶层的类名来命名

　　　大小写敏感

　　　扩展名为 .java

（2）文件编码：UTF-8

　　源文件编码格式为UTF-8

（3）特殊字符

　　A.空白字符

　　　　除了行结束符序列，ASCII水平空格字符(0x20，即空格)是源文件中唯一允许出现的空白字符

　　　　这意味着：

　　　　　　★ 所有其它字符串中的空白字符都要进行转义

　　　　　　★ 制表符不用于缩进

　　B.特殊转义序列

　　　　对于具有特殊转义序列的任何字符(\b, \t, \n, \f, \r, ", '及)，要使用它的转义序列，而不是相应的八进制(比如 \012)或Unicode(比如 \u000a)转义

　　C.非ASCII字符

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

3.源文件结构

　　一个源文件包含(按顺序地)：

　　★ 许可证或版权信息(如有需要)

　　★ package语句

　　★ import语句

　　★ 一个顶级类(只有一个)

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

（1）许可证或版权信息

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

（2）package语句

　　package语句不换行，列限制(4.4节)并不适用于package语句。(即package语句写在一行里)

（3）import语句

　　A. import不要使用通配符

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

　　B. 不要换行

　　　　import语句不换行，列限制(4.4节)并不适用于import语句

　　　　(每个import语句独立成行)

　　C.顺序和间距

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

★ 所有的静态导入独立成组

★com.google imports(仅当这个源文件是在 com.google包下)

★第三方的包。每个顶级包为一组，字典序。例如：android, com, junit, org, sun

★java imports

★javax imports

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

（4）类声明

　　A.只有一个顶级类声明

　　　　每个顶级类都在一个与它同名的源文件中(当然，还包含 .java后缀)

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

　　B.类成员顺序

　　　　类的成员顺序对易学性有很大的影响，但这也不存在唯一的通用法则

　　　　每个类应该以某种逻辑去排序它的成员，维护者应该要能解释这种排序逻辑

　　　　新的方法不能总是习惯性地添加到类的结尾，这就是按时间顺序来排序的

　　　　b1.重载：永不分离

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

4.格式

　　块状结构(block-like construct)指的是一个类，方法或构造函数的主体

　　数组初始化中的初始值可被选择性地视为块状结构

（1）大括号

　　A.使用大括号(即使是可选的)

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

　　B.非空块：K & R 风格

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

　　★ 左大括号前不换行

　　★ 左大括号后换行

　　★ 右大括号前换行

　　★ 如果右大括号是一个语句、函数体或类的终止，则右大括号后换行; 否则不换行

　　C.空块

　　　　可以用简洁版本

　　　　一个空的块状结构里什么也不包含，大括号可以简洁地写成 {}，不需要换行。

　　　　例外：如果它是一个多块语句的一部分(if/else 或 try/catch/finally) ，即使大括号内没内容，右大括号也要换行。

（2）块缩进：2个空格

　　每当开始一个新的块，缩进增加2个空格

　　当块结束时，缩进返回先前的缩进级别

　　缩进级别适用于代码和注释

（3） 一行一个语句

　　每个语句后要换行

（4） 列限制：80或100

　　一个项目可以选择一行80个字符或100个字符的列限制，除了下述例外，任何一行如果超过这个字符数限制，必须自动换行

例外：

★ 不可能满足列限制的行(例如，Javadoc中的一个长URL，或是一个长的JSNI方法参考)

★ package和 import语句

★ 注释中那些可能被剪切并粘贴到shell中的命令行

（5）自动换行

　　术语说明：

　　　　自动换行(line-wrapping)——一行长代码为了避免超出列限制(80或100个字符)而被分为多行

　　　　Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题(是合理缩短命名长度吧)

　　A.从哪里断开

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

　　　　　　★ 如果在 非赋值运算符处断开，那么在该符号前断开(比如+，它将位于下一行)

　　　　　　注意：

　　　　　　　　也适用于以下“类运算符”符号：点分隔符(.)，类型界限中的&（ )，catch块中的管道符号( catch(FooException|BarExceptione)

　　　　　　★ 如果在 赋值运算符处断开，通常的做法是在该符号后断开(比如=，它与前面的内容留在同一行)

　　　　　　注意：

　　　　　　　　也适用于 foreach语句中的分号

　　　　　　★ 方法名或构造函数名与左括号留在同一行

　　　　　　★ 逗号(,)与其前面的内容留在同一行

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

　　　　自动换行时，第一行后的每一行至少比第一行多缩进4个空格

　　　　当存在连续自动换行时，缩进可能会多缩进不只4个空格(语法元素存在多级时)

　　　　一般，两个连续行使用相同的缩进当且仅当它们开始于同级语法元素

（6）空白

　　A.垂直空白

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

★ 类内连续的成员之间：字段，构造函数，方法，嵌套类，静态初始化块，实例初始化块

　　- 例外：两个连续字段之间的空行是可选的，用于字段的空行主要用来对字段进行逻辑分组

★ 在函数体内，语句的逻辑分组间使用空行

★ 类内的第一个成员前或最后一个成员后的空行是可选的

★ 要满足本文档中其他节的空行要求(比如3.3节：import语句)

　　　　多个连续的空行是允许的

　　B.水平空白

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

　　　　★ 分隔任何保留字与紧随其后的左括号( ()(如 if,forcatch等)。

　　　　★ 分隔任何保留字与其前面的右大括号( })(如 else,catch)。

　　　　★ 在任何左大括号前( {)，两个例外：

　　　　@SomeAnnotation({a,b})(不使用空格)

　　　　　　　　String[][]x=foo;(大括号间没有空格，见下面的Note)

　　　　　　　　在任何二元或三元运算符的两侧。也适用于以下“类运算符”符号

　　　　　　　　 　　类型界限中的&( )

　　　　　　　　　　　　①catch块中的管道符号( catch(FooException|BarExceptione)

　　　　　　　　　　　　②foreach语句中的分号

Ⅰ.在 ,:;及右括号( ))后

Ⅱ.如果在一条语句后做注释，则双斜杠(//)两边都要空格。可以允许多个空格

Ⅲ.类型和变量之间：List list

Ⅳ.数组初始化中，大括号内的空格是可选的，即 newint[]{5,6}和 newint[]{5,6}都是可以的

　　C.水平对齐：不做要求

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

　　Tip：

　　　　对齐可增加代码可读性，但它为日后的维护带来问题。

　　　　考虑未来某个时候，我们需要修改一堆对齐的代码中的一行。

　　　　这可能导致原本很漂亮的对齐代码变得错位。

　　　　很可能它会提示你调整周围代码的空白来使这一堆代码重新水平对齐

（7）用小括号来限定组：推荐

（8）具体结构

　　A.枚举类

　　　　枚举常量间用逗号隔开，换行可选

　　B.变量声明

　　　　b1. 每次只声明一个变量

　　　　　　不要使用组合声明，比如 inta,b;

　　　　b2.需要时才声明，并尽快进行初始化

　　　　　　不要在一个代码块的开头把局部变量一次性都声明了(这是c语言的做法)，而是在第一次需要使用它时才声明

　　　　　　局部变量在声明时最好就进行初始化，或者声明后尽快进行初始化

　　C.数组

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

　　　　c2.非C风格的数组声明

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

　　D.switch语句

　　　　术语说明：switch块的大括号内是一个或多个语句组。

　　　　每个语句组包含一个或多个switch标签( caseFOO:或 default:)，后面跟着一条或多条语句。

　　　　d1.缩进

　　　　与其它块状结构一致，switch块中的内容缩进为2个空格

　　　　每个switch标签后新起一行，再缩进2个空格，写下一条或多条语句

　　　　d2. Fall-through：注释

　　　　在一个switch块内，每个语句组

　　　　　　要么通过 break,continue,return或抛出异常来终止

　　　　　　要么通过一条注释来说明程序将继续执行到下一个语句组， 任何能表达这个意思的注释都是OK的。

　　　　d3.default的情况要写出来

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

　　E. 注解(Annotations)

　　　　注解紧跟在文档块后面，应用于类、方法和构造函数，一个注解独占一行

　　　　那些换行不属于自动换行的，缩进级别不变

@Override@Nullablepublic String getNameIfPresent() { ... }

　　　　例外：单个的注解可以和签名的第一行出现在同一行。

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

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

　　　　参数和局部变量注解没有特定规则

　　F.注释

　　　　f1.块注释风格

　　　　　　块注释与其周围的代码在同一缩进级别。

　　　　　　可以是 /* ... */风格，也可以是 // ...风格

　　　　　　对于多行的 /* ... */注释，后续行必须从 *开始， 并且与前一行的 *对齐

　　　　　　注释不要封闭在由星号或其它字符绘制的框架里

　　G.Modifiers

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

5.命名约定

（1） 对所有标识符都通用的规则

　　标识符只能使用ASCII字母和数字，因此每个有效的标识符名称都能匹配正则表达式 \w+

（2）标识符类型的规则

　　A.包名

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

　　B.类名

　　　　类名都以 UpperCamelCase风格编写

　　　　类名通常是名词或名词短语，接口名称有时可能是形容词或形容词短语

　　　　现在还没有特定的规则或行之有效的约定来命名注解类型

　　　　测试类的命名以它要测试的类的名称开始，以 Test结束。例如， HashTest或 HashIntegrationTest

　　C.方法名

　　　　方法名都以 lowerCamelCase风格编写

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

　　　　下划线可能出现在JUnit测试方法名称中用以分隔名称的逻辑组件

　　　　一个典型的模式是：test<MethodUnderTest>_<state>，例如 testPop_emptyStack。并不存在唯一正确的方式来命名测试方法

　　D.常量名

　　　　常量名命名模式为 CONSTANT_CASE，全部字母大写，用下划线分隔单词

　　　　每个常量都是一个静态final字段，但不是所有静态final字段都是常量

　　　　一直不变的为常量

　　E.非常量字段名

　　　　非常量字段名以 lowerCamelCase风格编写

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

　　F.参数名

　　　　参数名以 lowerCamelCase风格编写

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

　　G.局部变量名

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

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

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

　　H.类型变量名

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

　　　　★ 单个的大写字母，后面可以跟一个数字(如：E, T, X, T2)

　　　　★ 以类命名方式(5.2.2节)，后面加个大写的T(如：RequestT, FooBarT)

（3）驼峰式命名法(CamelCase)

　　驼峰式命名法分大驼峰式命名法( UpperCamelCase)和小驼峰式命名法( lowerCamelCase)。

　　英语词转换方案

名字从 散文形式(prose form)开始:

　　　　★ 把短语转换为纯ASCII码，并且移除任何单引号。例如：”Müller’s algorithm”将变成”Muellers algorithm”

　　　　★ 把这个结果切分成单词，在空格或其它标点符号(通常是连字符)处分割开

　　　　　　　　- 推荐：

　　　　　　　　　　如果某个单词已经有了常用的驼峰表示形式，按它的组成将它分割开(如”AdWords”将分割成”ad words”)

　　　　　　　　　　需要注意的是”iOS”并不是一个真正的驼峰表示形式，因此该推荐对它并不适用

　　　　★ 现在将所有字母都小写(包括缩写)，然后将单词的第一个字母大写：

• • • 每个单词的第一个字母都大写，来得到大驼峰式命名
    • 除了第一个单词，每个单词的第一个字母都大写，来得到小驼峰式命名

　　　　★ 将所有的单词连接起来得到一个标识符

6.编程实践

（1） @Override：能用则用

　　只要是合法的，就把 @Override注解给用上

（2）捕获的异常：不能忽视

（3）静态成员：使用类进行调用

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

（4）Finalizers: 禁用

　　Tip：不要使用finalize

7.Javadoc

（1）格式

　　A.一般形式

　　　　a1.基本格式

/** 
 * Multiple lines of Javadoc text are written here, 
 * wrapped normally...
 */
public int method(String p1) { ... }

　　　　单行格式

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

　　a2.段落

　　　　空行(即，只包含最左侧星号的行)会出现在段落之间和Javadoc标记(@XXX)之前(如果有的话)

　　　　除了第一个段落，每个段落第一个单词前都有标签 <p>，并且它和第一个单词间没有空格

　　a3.Javadoc标记

　　　　标准的Javadoc标记按以下顺序出现：@param, @return, @throws, @deprecated, 前面这4种标记如果出现，描述都不能为空

　　　　当描述无法在一行中容纳，连续行需要至少再缩进4个空格

（2）摘要片段

　　每个类或成员的Javadoc以一个简短的摘要片段开始

　　这个片段是非常重要的，在某些情况下，它是唯一出现的文本，比如在类和方法索引中

　　这只是一个小片段，可以是一个名词短语或动词短语，但不是一个完整的句子。

　　Tip：

　　　　一个常见的错误是把简单的Javadoc写成 /** @return the customer ID */，这是不正确的

　　　　它应该写成 /** Returns the customer ID. */

（3）哪里需要使用Javadoc

　　至少在每个public类及它的每个public和protected成员处使用Javadoc

　　例外

　　　　不言自明的方法

　　　　重写

　　　　可选的Javadoc

　　　　　　对于包外不可见的类和方法，如有需要，也是要使用Javadoc的