`这样的html标签，以及`<` `"` 这样的html转义字符，严重影响了直接阅读代码时的直观性，而直接阅读代码的几率其实比看Html版的JavaDoc大得多。
另外IDE对JavaDoc的格式化也要求``之类的标签来换行，可以配置让IDE不对JavaDoc的格式化。
----
**Rule 8. 【推荐】注释不要为了英文而英文**
如果没有国际化要求，中文能表达得更清晰时还是用中文。
----
**Rule 9. 【推荐】TODO 标记，清晰说明代办事项和处理人**
“对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释. ”
清晰描述待修改的事项，保证过几个月后仍然能够清楚要做什么修改。
如果近期会处理的事项，写明处理人。如果远期的，写明提出人。
通过 IDE 和 Sonar 的标记扫描，经常清理此类标记，线上故障经常来源于这些标记但未处理的代码。
正例：
```java
// TODO(who): to do what.
// TODO(who): when to do what.
// TODO(calvin): use xxx to replace yyy.
```
反例：
```java
// TODO: refactor it
```
不推荐使用 FIXME 标记。这样，在项目中搜索 TODO 就可以得到完整的 TODO list，而不需要搜索 TODO 和 FIXME。
* [Sonar: Track uses of "TODO" tags](https://rules.sonarsource.com/java/RSPEC-1135)
----
**Rule 10. 【推荐】合理处理注释掉的代码**
如果后续会恢复此段代码，在目标代码上方用`///`说明注释动机，而不是简单的注释掉代码。
如果很大概率不再使用，则直接删除（版本管理工具保存了历史代码）。
* [Sonar: Sections of code should not be "commented out"](https://rules.sonarsource.com/java/RSPEC-125)
----
================================================
FILE: docs/standard/chapter04.md
================================================
# (四) 方法设计
**Rule 1. 【推荐】方法的长度度量**
方法尽量不要超过100行，或其他团队共同商定的行数。
另外，方法长度超过8000个字节码时，将不会被JIT编译成二进制码。
* [Sonar-107: Methods should not have too many lines](https://rules.sonarsource.com/java/RSPEC-107)，默认值改为100
* Facebook-Contrib:Performance - This method is too long to be compiled by the JIT
----
**Rule 2. 【推荐】方法的语句在同一个抽象层级上**
反例：一个方法里，前20行代码在进行很复杂的基本价格计算，然后调用一个折扣计算函数，再调用一个赠品计算函数。
此时可将前20行也封装成一个价格计算函数，使整个方法在同一抽象层级上。
----
**Rule 3. 【推荐】为了帮助阅读及方法内联，将小概率发生的异常处理及其他极小概率进入的代码路径，封装成独立的方法**
```java
if(seldomHappenCase) {
hanldMethod();
}
try {
...
} catch(SeldomHappenException e) {
handleException();
}
```
----
**Rule 4. 【推荐】尽量减少重复的代码，抽取方法**
超过5行以上重复的代码，都可以考虑抽取公用的方法。
----
**Rule 5. 【推荐】方法参数最好不超过3个，最多不超过7个**
1）如果多个参数同属于一个对象，直接传递对象。
例外: 你不希望依赖整个对象，传播了类之间的依赖性。
2）将多个参数合并为一个新创建的逻辑对象。
例外: 多个参数之间毫无逻辑关联。
3）将函数拆分成多个函数，让每个函数所需的参数减少。
* [Sonar-107: Methods should not have too many parameters](https://rules.sonarsource.com/java/RSPEC-107)
----
**Rule 6.【推荐】下列情形，需要进行参数校验**
1） 调用频次低的方法。
2） 执行时间开销很大的方法。此情形中，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，代价更大。
3） 需要极高稳定性和可用性的方法。
4） 对外提供的开放接口，不管是RPC/HTTP/公共类库的API接口。
如果使用Apache Validate 或 Guava Precondition进行校验，并附加错误提示信息时，注意不要每次校验都做一次字符串拼接。
```java
//WRONG
Validate.isTrue(length > 2, "length is "+keys.length+", less than 2", length);
//RIGHT
Validate.isTrue(length > 2, "length is %d, less than 2", length);
```
----
**Rule 7.【推荐】下列情形，不需要进行参数校验**
1） 极有可能被循环调用的方法。
2） 底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。
比如，一般DAO层与Service层都在同一个应用中，所以DAO层的参数校验，可以省略。
3） 被声明成private，或其他只会被自己代码所调用的方法，如果能够确定在调用方已经做过检查，或者肯定不会有问题则可省略。
即使忽略检查，也尽量在方法说明里注明参数的要求，比如vjkit中的@NotNull，@Nullable标识。
----
**Rule 8.【推荐】禁用assert做参数校验**
assert断言仅用于测试环境调试，无需在生产环境时进行的校验。因为它需要增加-ea启动参数才会被执行。而且校验失败会抛出一个AssertionError(属于Error，需要捕获Throwable）
因此在生产环境进行的校验，需要使用Apache Commons Lang的Validate或Guava的Precondition。
----
**Rule 9.【推荐】返回值可以为Null，可以考虑使用JDK8的Optional类**
不强制返回空集合，或者空对象。但需要添加注释充分说明什么情况下会返回null值。
本手册明确`防止NPE是调用者的责任`。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null的情况。
JDK8的Optional类的使用这里不展开。
----
**Rule 10.【推荐】返回值可以为内部数组和集合**
如果觉得被外部修改的可能性不大，或没有影响时，不强制在返回前包裹成Immutable集合，或进行数组克隆。
----
**Rule 11.【推荐】不能使用有继承关系的参数类型来重载方法**
因为方法重载的参数类型是根据编译时表面类型匹配的，不根据运行时的实际类型匹配。
```java
class A {
void hello(List list);
void hello(ArrayList arrayList);
}
List arrayList = new ArrayList();
// 下句调用的是hello(List list)，因为arrayList的定义类型是List
a.hello(arrayList);
```
----
**Rule 12.【强制】正被外部调用的接口，不允许修改方法签名，避免对接口的调用方产生影响**
只能新增新接口，并对已过时接口加@Deprecated注解，并清晰地说明新接口是什么。
----
**Rule 13.【推荐】不使用`@Deprecated`的类或方法**
接口提供方既然明确是过时接口并提供新接口，那么作为调用方来说，有义务去考证过时方法的新实现是什么。
比如java.net.URLDecoder 中的方法decode(String encodeStr) 这个方法已经过时，应该使用双参数decode(String source, String encode)。
----
**Rule 14.【推荐】不使用不稳定方法，如com.sun.\*包下的类，底层类库中internal包下的类**
`com.sun.*`，`sun.*`包下的类，或者底层类库中名称为internal的包下的类，都是不对外暴露的，可随时被改变的不稳定类。
* [Sonar-1191: Classes from "sun.*" packages should not be used](https://rules.sonarsource.com/java/RSPEC-1191)
----
================================================
FILE: docs/standard/chapter05.md
================================================
# (五) 类设计
**Rule 1. 【推荐】类成员与方法的可见性最小化**
任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。思考：如果是一个private的方法，想删除就删除，可是一个public的service方法，或者一个public的成员变量，删除一下，不得手心冒点汗吗？
例外：为了单元测试，有时也可能将访问范围扩大，此时需要加上JavaDoc说明或vjkit中的`@VisibleForTesting`注解。
----
**Rule 2.【推荐】 减少类之间的依赖**
比如如果A类只依赖B类的某个属性，在构造函数和方法参数中，只传入该属性。让阅读者知道，A类只依赖了B类的这个属性，而不依赖其他属性，也不会调用B类的任何方法。
```java
a.foo(b); //WRONG
a.foo(b.bar); //RIGHT
```
----
**Rule 3.【推荐】 定义变量与方法参数时，尽量使用接口而不是具体类**
使用接口可以保持一定的灵活性，也能向读者更清晰的表达你的需求：变量和参数只是要求有一个Map，而不是特定要求一个HashMap。
例外：如果变量和参数要求某种特殊类型的特性，则需要清晰定义该参数类型，同样是为了向读者表达你的需求。
----
**Rule 4. 【推荐】类的长度度量**
类尽量不要超过300行，或其他团队共同商定的行数。
对过大的类进行分拆时，可考虑其内聚性，即类的属性与类的方法的关联程度，如果有些属性没有被大部分的方法使用，其内聚性是低的。
----
**Rule 5.【推荐】 构造函数如果有很多参数，且有多种参数组合时，建议使用Builder模式**
```java
Executor executor = new ThreadPoolBuilder().coreThread(10).queueLenth(100).build();
```
即使仍然使用构造函数，也建议使用chain constructor模式，逐层加入默认值传递调用，仅在参数最多的构造函数里实现构造逻辑。
```java
public A(){
A(DEFAULT_TIMEOUT);
}
public A(int timeout) {
...
}
```
----
**Rule 6.【推荐】构造函数要简单，尤其是存在继承关系的时候**
可以将复杂逻辑，尤其是业务逻辑，抽取到独立函数，如init()，start()，让使用者显式调用。
```java
Foo foo = new Foo();
foo.init();
```
----
**Rule 7.【强制】所有的子类覆写方法，必须加`@Override`注解**
比如有时候子类的覆写方法的拼写有误，或方法签名有误，导致没能真正覆写，加`@Override`可以准确判断是否覆写成功。
而且，如果在父类中对方法签名进行了修改，子类会马上编译报错。
另外，也能提醒阅读者这是个覆写方法。
最后，建议在IDE的Save Action中配置自动添加`@Override`注解，如果无意间错误同名覆写了父类方法也能被发现。
* [Sonar-1161: "@Override" should be used on overriding and implementing methods](https://rules.sonarsource.com/java/RSPEC-1161)
----
**Rule 8.【强制】静态方法不能被子类覆写。**
因为它只会根据表面类型来决定调用的方法。
```java
Base base = new Children();
// 下句实际调用的是父类的静态方法，虽然对象实例是子类的。
base.staticMethod();
```
----
**Rule 9.静态方法访问的原则**
**9.1【推荐】避免通过一个类的对象引用访问此类的静态变量或静态方法，直接用类名来访问即可**
目的是向读者更清晰传达调用的是静态方法。可在IDE的Save Action中配置自动转换。
```java
int i = objectA.staticMethod(); // WRONG
int i = ClassA.staticMethod(); // RIGHT
```
* [Sonar-2209: "static" members should be accessed statically](https://rules.sonarsource.com/java/RSPEC-2209)
* [Sonar-2440: Classes with only "static" methods should not be instantiated](https://rules.sonarsource.com/java/RSPEC-2440)
**9.2 【推荐】除测试用例，不要static import 静态方法**
静态导入后忽略掉的类名，给阅读者造成障碍。
例外：测试环境中的assert语句，大家都太熟悉了。
* [Sonar-3030: Classes should not have too many "static" imports](https://rules.sonarsource.com/java/RSPEC-3030) 但IDEA经常自动转换static import，所以暂不作为规则。
**9.3【推荐】尽量避免在非静态方法中修改静态成员变量的值**
```java
// WRONG
public void foo() {
ClassA.staticFiled = 1;
}
```
* [Sonar-2696: Instance methods should not write to "static" fields](https://rules.sonarsource.com/java/RSPEC-2696)
* [Sonar-3010: Static fields should not be updated in constructors](https://rules.sonarsource.com/java/RSPEC-3010)
----
**Rule 10.【推荐】 内部类的定义原则**
当一个类与另一个类关联非常紧密，处于从属的关系，特别是只有该类会访问它时，可定义成私有内部类以提高封装性。
另外，内部类也常用作回调函数类，在JDK8下建议写成Lambda。
内部类分匿名内部类，内部类，静态内部类三种。
1) 匿名内部类 与 内部类，按需使用：
在性能上没有区别；当内部类会被多个地方调用，或匿名内部类的长度太长，已影响对调用它的方法的阅读时，定义有名字的内部类。
2) 静态内部类 与 内部类，优先使用静态内部类：
1. 非静态内部类持有外部类的引用，能访问外类的实例方法与属性。构造时多传入一个引用对性能没有太大影响，更关键的是向阅读者传递自己的意图，内部类会否访问外部类。
2. 非静态内部类里不能定义static的属性与方法。
* [Sonar-2694: Inner classes which do not reference their owning classes should be "static"](https://rules.sonarsource.com/java/RSPEC-2694)
* [Sonar-1604: Anonymous inner classes containing only one method should become lambdas](https://rules.sonarsource.com/java/RSPEC-1604)
----
**Rule 11.【推荐】使用getter/setter方法，还是直接public成员变量的原则。**
除非因为特殊原因方法内联失败，否则使用getter方法与直接访问成员变量的性能是一样的。
使用getter/setter，好处是可以进一步的处理：
1. 通过隐藏setter方法使得成员变量只读
2. 增加简单的校验逻辑
3. 增加简单的值处理，值类型转换等
建议通过IDE生成getter/setter。
但getter/seter中不应有复杂的业务处理，建议另外封装函数，并且不要以getXX/setXX命名。
如果是内部类，以及无逻辑的POJO/VO类，使用getter/setter除了让一些纯OO论者感觉舒服，没有任何的好处，建议直接使用public成员变量。
例外：有些序列化框架只能从getter/setter反射，不能直接反射public成员变量。
----
**Rule 12.【强制】POJO类必须覆写toString方法。**
便于记录日志，排查问题时调用POJO的toString方法打印其属性值。否则默认的Object.toString()只打印`类名@数字`的无效信息。
----
**Rule 13. hashCode和equals方法的处理，遵循如下规则:**
**13.1【强制】只要重写equals，就必须重写hashCode。 而且选取相同的属性进行运算。**
**13.2【推荐】只选取真正能决定对象是否一致的属性，而不是所有属性，可以改善性能。**
**13.3【推荐】对不可变对象，可以缓存hashCode值改善性能（比如String就是例子）。**
**13.4【强制】类的属性增加时，及时重新生成toString，hashCode和equals方法。**
* [Sonar-1206: "equals(Object obj)" and "hashCode()" should be overridden in pairs](https://rules.sonarsource.com/java/RSPEC-1206)
----
**Rule 14.【强制】使用 IDE 生成 toString、hashCode 和 equals 方法。**
使用 IDE 生成而不是手写，能保证 toString 有统一的格式，equals 和 hashCode 则避免不正确的 null 值处理。
子类生成 toString 时，还需要勾选父类的属性。
----
**Rule 15. 【强制】Object的equals方法容易抛空指针异常，应使用常量或确定非空的对象来调用equals**
推荐使用java.util.Objects#equals（JDK7引入的工具类）
```java
"test".equals(object); //RIGHT
Objects.equals(object, "test"); //RIGHT
```
* [Sonar-1132: Strings literals should be placed on the left side when checking for equality](https://rules.sonarsource.com/java/RSPEC-1132)
----
**Rule 16.【强制】除了保持兼容性的情况，总是移除无用属性、方法与参数**
特别是private的属性、方法、内部类，private方法上的参数，一旦无用立刻移除。信任代码版本管理系统。
* [Sonar-3985: Unused "private" classes should be removed](https://rules.sonarsource.com/java/RSPEC-3985)
* [Sonar-1068: Unused "private" fields should be removed](https://rules.sonarsource.com/java/RSPEC-1068)
* [Sonar: Unused "private" methods should be removed](https://rules.sonarsource.com/java/RSPEC-1144)
* [Sonar-1481: Unused local variables should be removed](https://rules.sonarsource.com/java/RSPEC-1481)
* [Sonar-1172: Unused method parameters should be removed](https://rules.sonarsource.com/java/RSPEC-1172) Sonar-VJ版只对private方法的无用参数告警。
----
**Rule 17.【推荐】final关键字与性能无关，仅用于下列不可修改的场景**
1） 定义类及方法时，类不可继承，方法不可覆写；
2） 定义基本类型的函数参数和变量，不可重新赋值；
3） 定义对象型的函数参数和变量，仅表示变量所指向的对象不可修改，而对象自身的属性是可以修改的。
----
**Rule 18.【推荐】得墨忒耳法则，不要和陌生人说话**
以下调用，一是导致了对A对象的内部结构(B,C)的紧耦合，二是连串的调用很容易产生NPE，因此链式调用尽量不要过长。
```java
obj.getA().getB().getC().hello();
```
----
================================================
FILE: docs/standard/chapter06.md
================================================
# (六) 控制语句
**Rule 1. 【强制】if, else, for, do, while语句必须使用大括号，即使只有单条语句**
曾经试过合并代码时，因为没加括号，单条语句合并成两条语句后，仍然认为只有单条语句，另一条语句在循环外执行。
其他增加调试语句等情况也经常引起同样错误。
可在IDE的Save Action中配置自动添加。
```java
if (a == b) {
...
}
```
例外：一般由IDE生成的equals()函数
* [Sonar-121: Control structures should use curly braces](https://rules.sonarsource.com/java/RSPEC-121) Sonar-VJ版豁免了equals()函数
----
**Rule 2.【推荐】少用if-else方式，多用哨兵语句式以减少嵌套层次**
```java
if (condition) {
...
return obj;
}
// 接着写else的业务逻辑代码;
```
* Facebook-Contrib: Style - Method buries logic to the right (indented) more than it needs to be
----
**Rule 3.【推荐】限定方法的嵌套层次**
所有if/else/for/while/try的嵌套，当层次过多时，将引起巨大的阅读障碍，因此一般推荐嵌套层次不超过4。
通过抽取方法，或哨兵语句（见Rule 2）来减少嵌套。
```java
public void applyDriverLicense() {
if (isTooYoung()) {
System.out.println("You are too young to apply driver license.");
return;
}
if (isTooOld()) {
System.out.println("You are too old to apply driver license.");
return;
}
System.out.println("You've applied the driver license successfully.");
return;
}
```
* [Sonar-134: Control flow statements "if", "for", "while", "switch" and "try" should not be nested too deeply](https://rules.sonarsource.com/java/RSPEC-134)，增大为4
----
**Rule 4.【推荐】布尔表达式中的布尔运算符(&&,||)的个数不超过4个，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性**
```java
//WRONG
if ((file.open(fileName, "w") != null) && (...) || (...)|| (...)) {
...
}
//RIGHT
boolean existed = (file.open(fileName, "w") != null) && (...) || (...);
if (existed || (...)) {
...
}
```
* [Sonar-1067: Expressions should not be too complex](https://rules.sonarsource.com/java/RSPEC-1067)，增大为4
----
**Rule 5.【推荐】简单逻辑，善用三目运算符，减少if-else语句的编写**
```java
s != null ? s : "";
```
----
**Rule 6.【推荐】减少使用取反的逻辑**
不使用取反的逻辑，有利于快速理解。且大部分情况，取反逻辑存在对应的正向逻辑写法。
```java
//WRONG
if (!(x >= 268) { ... }
//RIGHT
if (x < 268) { ... }
```
* [Sonar-1940: Boolean checks should not be inverted](https://rules.sonarsource.com/java/RSPEC-1940)
----
**Rule 7.【推荐】表达式中，能造成短路概率较大的逻辑尽量放前面，使得后面的判断可以免于执行**
```java
if (maybeTrue() || maybeFalse()) { ... }
if (maybeFalse() && maybeTrue()) { ... }
```
----
**Rule 8.【强制】switch的规则**
1）在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；
2）在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。
```java
String animal = "tomcat";
switch (animal) {
case "cat":
System.out.println("It's a cat.");
break;
case "lion": // 执行到tiger
case "tiger":
System.out.println("It's a beast.");
break;
default:
// 什么都不做，也要有default
break;
}
```
* [Sonar: "switch" statements should end with "default" clauses](https://rules.sonarsource.com/java/RSPEC-131)
----
**Rule 9.【推荐】循环体中的语句要考量性能，操作尽量移至循环体外处理**
1）不必要的耗时较大的对象构造；
2）不必要的try-catch（除非出错时需要循环下去）。
----
**Rule 10.【推荐】能用while循环实现的代码，就不用do-while循环**
while语句能在循环开始的时候就看到循环条件，便于帮助理解循环内的代码；
do-while语句要在循环最后才看到循环条件，不利于代码维护，代码逻辑容易出错。
----
================================================
FILE: docs/standard/chapter07.md
================================================
# (七) 基本类型与字符串
**Rule 1. 原子数据类型(int等)与包装类型(Integer等)的使用原则**
**1.1 【推荐】需要序列化的POJO类属性使用包装数据类型**
**1.2 【推荐】RPC方法的返回值和参数使用包装数据类型**
**1.3 【推荐】局部变量尽量使用基本数据类型**
包装类型的坏处:
1）Integer 24字节，而原子类型 int 4字节。
2）包装类型每次赋值还需要额外创建对象，如Integer var = 200， 除非数值在缓存区间内(见Integer.IntegerCache与Long.LongCache)才会复用已缓存对象。默认缓存区间为-128到127，其中Integer的缓存区间还受启动参数的影响，如-XX:AutoBoxCacheMax=20000。
3）包装类型还有==比较的陷阱（见规则3）
包装类型的好处:
1）包装类型能表达 null 的语义。
比如数据库的查询结果可能是null，如果用基本数据类型有NPE风险。又比如显示成交总额涨跌情况，如果调用的RPC服务不成功时，应该返回null，显示成-%，而不是0%。
2）集合需要包装类型，除非使用数组，或者特殊的原子类型集合。
3）泛型需要包装类型，如`Result`。
----
**Rule 2.原子数据类型与包装类型的转换原则**
**2.1【推荐】自动转换(AutoBoxing)有一定成本，调用者与被调用函数间尽量使用同一类型，减少默认转换**
```java
//WRONG, sum 类型为Long， i类型为long，每次相加都需要AutoBoxing。
Long sum=0L;
for( long i = 0; i < 10000; i++) {
sum+=i;
}
//RIGHT, 准确使用API返回正确的类型
Integer i = Integer.valueOf(str);
int i = Integer.parseInt(str);
```
* [Sonar-2153: Boxing and unboxing should not be immediately reversed](https://rules.sonarsource.com/java/RSPEC-2153)
**2.2 【推荐】自动拆箱有可能产生NPE，要注意处理**
```java
//如果intObject为null，产生NPE
int i = intObject;
```
----
**Rule 3. 数值equals比较的原则**
**3.1【强制】 所有包装类对象之间值的比较，全部使用equals方法比较**
\==判断对象是否同一个。Integer var = ?在缓存区间的赋值（见规则1），会复用已有对象，因此这个区间内的Integer使用==进行判断可通过，但是区间之外的所有数据，则会在堆上新产生，不会通过。因此如果用\== 来比较数值，很可能在小的测试数据中通过，而到了生产环境才出问题。
**3.2【强制】 BigDecimal需要使用compareTo()**
因为BigDecimal的equals()还会比对精度，2.0与2.00不一致。
* Facebook-Contrib: Correctness - Method calls BigDecimal.equals()
**3.3【强制】 Atomic\* 系列，不能使用 equals 方法**
因为 Atomic\* 系列没有覆写 equals 方法。
```java
// RIGHT
if (counter1.get() == counter2.get()) {
// ...
}
```
* [Sonar-2204: ".equals()" should not be used to test the values of "Atomic" classes](https://rules.sonarsource.com/java/RSPEC-2204)
**3.4【强制】 double 及 float 的比较，要特殊处理**
因为精度问题，浮点数间的 equals 非常不可靠，在 vjkit 的 NumberUtil 中有对应的封装函数。
```java
float f1 = 0.15f;
float f2 = 0.45f/3; // 实际等于0.14999999
// 反例
if (f1 == f2) {
// ...
}
// 反例
if (Double.compare(f1, f2) == 0) {
// ...
}
// 正例
// 绝对误差
static final float EPSILON = 0.00001f;
if (Math.abs(f1 - f2) < EPSILON) {
// ...
}
// 正例
// 相对误差
static final float EPSILON = 0.001f;
if (Math.abs(f1 - f2) / (Math.abs(f1) + Math.abs(f2)) < EPSILON) {
// ...
}
```
推荐使用“相对误差”的方式比较浮点数。
* [Sonar-1244: Floating point numbers should not be tested for equality](https://rules.sonarsource.com/java/RSPEC-1244)
----
**Rule 4. 数字类型的计算原则**
**4.1【强制】数字运算表达式，因为先进行等式右边的运算，再赋值给等式左边的变量，所以等式两边的类型要一致**
例子1: int与int相除后，哪怕被赋值给float或double，结果仍然是四舍五入取整的int。
需要强制将除数或被除数转换为float或double。
```java
double d = 24/7; //结果是3.0
double d = (double)24/7; //结果是正确的3.42857
```
例子2： int与int相乘，哪怕被赋值给long，仍然会溢出。
需要强制将乘数的一方转换为long。
```java
long l = Integer.MAX_VALUE * 2; // 结果是溢出的－2
long l = Integer.MAX_VALUE * 2L; //结果是正确的4294967294
```
另外，int的最大值约21亿，留意可能溢出的情况。
* [Sonar-2184: Math operands should be cast before assignment](https://rules.sonarsource.com/java/RSPEC-2184)
**4.2【强制】数字取模的结果不一定是正数，负数取模的结果仍然负数**
取模做数组下标时，如果不处理负数的情况，很容易ArrayIndexOutOfBoundException。
另外，Integer.MIN_VALUE取绝对值也仍然是负数。因此，vjkit的MathUtil对上述情况做了安全的封装。
```java
-4 % 3 = -1;
Math.abs(Integer.MIN_VALUE) = -2147483648;
```
* Findbugs: Style - Remainder of hashCode could be negative
**4.3【推荐】 double 或 float 计算时有不可避免的精度问题**
```java
float f = 0.45f/3; //结果是0.14999999
double d1 = 0.45d/3; //结果是正确的0.15
double d2 = 1.03d - 0.42d; //结果是0.6100000000000001
```
尽量用double而不用float，但如果是金融货币的计算，则必须使用如下选择：
选项1， 使用性能较差的BigDecimal。BigDecimal还能精确控制四舍五入或是其他取舍的方式。
选项2， 在预知小数精度的情况下，将浮点运算放大为整数计数，比如货币以"分"而不是以"元"计算。
* [Sonar-2164: Math should not be performed on floats](https://rules.sonarsource.com/java/RSPEC-2164)
----
**Rule 5. 【推荐】如果变量值仅有有限的可选值，用枚举类来定义常量**
尤其是变量还希望带有名称之外的延伸属性时，如下例：
```java
//WRONG
public String MONDAY = "MONDAY";
public int MONDAY_SEQ = 1;
//RIGHT
public enum SeasonEnum {
SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
int seq;
SeasonEnum(int seq) { this.seq = seq; }
}
```
业务代码中不要依赖ordinary()函数进行业务运算，而是自定义数字属性，以免枚举值的增减调序造成影响。 例外：永远不会有变化的枚举，比如上例的一年四季。
----
**Rule 6. 字符串拼接的原则**
**6.1 【推荐】 当字符串拼接不在一个命令行内写完，而是存在多次拼接时(比如循环)，使用StringBuilder的append()**
```java
String s = "hello" + str1 + str2; //Almost OK，除非初始长度有问题，见第3点.
String s = "hello"; //WRONG
if (condition) {
s += str1;
}
String str = "start"; //WRONG
for (int i = 0; i < 100; i++) {
str = str + "hello";
}
```
反编译出的字节码文件显示，其实每条用`+`进行字符拼接的语句，都会new出一个StringBuilder对象，然后进行append操作，最后通过toString方法返回String对象。所以上面两个错误例子，会重复构造StringBuilder，重复toString()造成资源浪费。
* [Sonar-1643: Strings should not be concatenated using '+' in a loop](https://rules.sonarsource.com/java/RSPEC-1643)
**6.2 【强制】 字符串拼接对象时，不要显式调用对象的toString()**
如上，`+`实际是StringBuilder，本身会调用对象的toString()，且能很好的处理null的情况。
```java
//WRONG
str = "result:" + myObject.toString(); // myObject 为 null时，抛 NPE
//RIGHT
str = "result:" + myObject; // myObject 为 null 时，输出 result:null
```
**6.3【强制】使用StringBuilder，而不是有所有方法都有同步修饰符的StringBuffer**
因为内联不成功，逃逸分析并不能抹除StringBuffer上的同步修饰符
* [Sonar-1149: Synchronized classes Vector, Hashtable, Stack and StringBuffer should not be used](https://rules.sonarsource.com/java/RSPEC-1149)
**6.4 【推荐】当拼接后字符串的长度远大于16时，指定StringBuilder的大概长度，避免容量不足时的成倍扩展**
**6.5 【推荐】如果字符串长度很大且频繁拼接，可考虑ThreadLocal重用StringBuilder对象**
参考BigDecimal的toString()实现，及vjkit中的StringBuilderHolder。
----
**Rule 7. 【推荐】字符操作时，优先使用字符参数，而不是字符串，能提升性能**
```java
//WRONG
str.indexOf("e");
//RIGHT
stringBuilder.append('a');
str.indexOf('e');
str.replace('m','z');
```
其他包括split等方法，在JDK String中未提供针对字符参数的方法，可考虑使用Apache Commons StringUtils 或Guava的Splitter。
* [Sonar-3027: String function use should be optimized for single characters](https://rules.sonarsource.com/java/RSPEC-3027)
----
**Rule 8. 【推荐】利用好正则表达式的预编译功能，可以有效加快正则匹配速度**
反例：
```java
//直接使用String的matches()方法
result = "abc".matches("[a-zA-z]");
//每次重新构造Pattern
Pattern pattern = Pattern.compile("[a-zA-z]");
result = pattern.matcher("abc").matches();
```
正例：
```java
//在某个地方预先编译Pattern，比如类的静态变量
private static Pattern pattern = Pattern.compile("[a-zA-z]");
...
//真正使用Pattern的地方
result = pattern.matcher("abc").matches();
```
----
================================================
FILE: docs/standard/chapter08.md
================================================
# (八) 集合处理
**Rule 1. 【推荐】底层数据结构是数组的集合，指定集合初始大小**
底层数据结构为数组的集合包括 ArrayList，HashMap，HashSet，ArrayDequeue等。
数组有大小限制，当超过容量时，需要进行复制式扩容，新申请一个是原来容量150% or 200%的数组，将原来的内容复制过去，同时浪费了内存与性能。HashMap/HashSet的扩容，还需要所有键值对重新落位，消耗更大。
默认构造函数使用默认的数组大小，比如ArrayList默认大小为10，HashMap为16。因此建议使用ArrayList(int initialCapacity)等构造函数，明确初始化大小。
HashMap/HashSet的初始值还要考虑加载因子:
为了降低哈希冲突的概率(Key的哈希值按数组大小取模后，如果落在同一个数组下标上，将组成一条需要遍历的Entry链)，默认当HashMap中的键值对达到数组大小的75%时，即会触发扩容。因此，如果预估容量是100，即需要设定`100/0.75 +1＝135`的数组大小。vjkit的MapUtil的Map创建函数封装了该计算。
如果希望加快Key查找的时间，还可以进一步降低加载因子，加大初始大小，以降低哈希冲突的概率。
----
**Rule 2. 【推荐】尽量使用新式的foreach语法遍历Collection与数组**
foreach是语法糖，遍历集合的实际字节码等价于基于Iterator的循环。
foreach代码一来代码简洁，二来有效避免了有多个循环或嵌套循环时，因为不小心的复制粘贴，用错了iterator或循环计数器(i,j)的情况。
----
**Rule 3. 【强制】不要在foreach循环里进行元素的remove/add操作，remove元素可使用Iterator方式**
```java
//WRONG
for (String str : list) {
if (condition) {
list.remove(str);
}
}
//RIGHT
Iterator it = list.iterator();
while (it.hasNext()) {
String str = it.next();
if (condition) {
it.remove();
}
}
```
* Facebook-Contrib: Correctness - Method modifies collection element while iterating
* Facebook-Contrib: Correctness - Method deletes collection element while iterating
----
**Rule 4. 【强制】使用entrySet遍历Map类集合Key/Value，而不是keySet 方式进行遍历**
keySet遍历的方式，增加了N次用key获取value的查询。
* [Sonar-2864:"entrySet()" should be iterated when both the key and value are needed](https://rules.sonarsource.com/java/RSPEC-2864)
----
**Rule 5. 【强制】当对象用于集合时，下列情况需要重新实现hashCode()和 equals()**
1） 以对象做为Map的KEY时；
2） 将对象存入Set时。
上述两种情况，都需要使用hashCode和equals比较对象，默认的实现会比较是否同一个对象（对象的引用相等）。
另外，对象放入集合后，会影响hashCode()，equals()结果的属性，将不允许修改。
* [Sonar-2141:Classes that don't define "hashCode()" should not be used in hashes](https://rules.sonarsource.com/java/RSPEC-2141)
----
**Rule 6. 【强制】高度注意各种Map类集合Key/Value能不能存储null值的情况**
| Map | Key | Value |
| -------- | -------- |-------- |
|HashMap|Nullable | Nullable|
|ConcurrentHashMap| NotNull| NotNull|
|TreeMap| NotNull| Nullable |
由于HashMap的干扰，很多人认为ConcurrentHashMap是可以置入null值。同理，Set中的value实际是Map中的key。
----
**Rule 7. 【强制】长生命周期的集合，里面内容需要及时清理，避免内存泄漏**
长生命周期集合包括下面情况，都要小心处理。
1） 静态属性定义；
2） 长生命周期对象的属性；
3） 保存在ThreadLocal中的集合。
如无法保证集合的大小是有限的，使用合适的缓存方案代替直接使用HashMap。
另外，如果使用WeakHashMap保存对象，当对象本身失效时，就不会因为它在集合中存在引用而阻止回收。但JDK的WeakHashMap并不支持并发版本，如果需要并发可使用Guava Cache的实现。
----
**Rule 8. 【强制】集合如果存在并发修改的场景，需要使用线程安全的版本**
1) 著名的反例，HashMap扩容时，遇到并发修改可能造成100%CPU占用。
推荐使用`java.util.concurrent(JUC)`工具包中的并发版集合，如ConcurrentHashMap等，优于使用Collections.synchronizedXXX()系列函数进行同步化封装(等价于在每个方法都加上synchronized关键字)。
例外：ArrayList所对应的CopyOnWriteArrayList，每次更新时都会复制整个数组，只适合于读多写很少的场景。如果频繁写入，可能退化为使用Collections.synchronizedList(list)。
2) 即使线程安全类仍然要注意函数的正确使用。
例如：即使用了 ConcurrentHashMap，但直接使用 get/put 方法，仍然可能会多线程间互相覆盖。
```java
//WRONG
E e = map.get(key);
if (e == null) {
e = new E();
map.put(key, e); //仍然能两条线程并发执行put，互相覆盖
}
return e;
//RIGHT
E e = map.get(key);
if (e == null) {
e = new E();
E previous = map.putIfAbsent(key, e);
if(previous != null) {
return previous;
}
}
return e;
```
----
**Rule 9. 【推荐】正确使用集合泛型的通配符**
`List`并不是`List