松果生活项目规划

一、编程规约

（一）命名规范

1. 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
3. 类名使用UpperCamelCase风格，必须遵从驼峰形式。
4. 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase风格，必须遵从驼峰形式。
5. 常量命名全部大写，单词间用下划线隔开。（Fujian等地名除外）
6. 中括号是数组类型的一部分，数组定义如下：String[] args;
7. POJO类中布尔类型的变量，都不要加is，否则部分框架解析会引起序列化错误。
8. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词，包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
9. 如果使用到了设计模式，建议在类名中体现出具体模式。
10. 接口类中的方法和属性不要加任何修饰符号（public也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
11. 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test结尾。
12. 杜绝完全不规范的缩写，避免望文不知义。
13. 为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
14. 如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。

（二）代码格式

1. 任何二目、三目运算符的左右两边都需要加一个空格

2. 在if/else/for/while/do语句中必须使用大括号，即使只有一行代码，避免使用下面的形式：if (condition) statements; 保留字与括号之间都必须加空格。

3. 尽量少用else， if-else的方式可以改写成：

   if(condition){
       ...
       return obj;
   }
   

4. 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

   • 左大括号前不换行。
   • 左大括号后换行。
   • 右大括号前换行。
   • 右大括号后还有else等代码则不换行；表示终止右大括号后必须换行。

5. 方法间必须要空行，方法参数在定义和传入时，多个参数逗号后边必须加空格。

6. 缩进使用四个空格而不是用Tab缩进，在IDE中设置Tab的格式为四个空格。左小括号和字符之间不出现空格 ； 同样，右小括号和字符之间也不出现空格。

7. 单行字符数限制不超过120个，超出需要换行，换行时遵循如下原则：

   • 第二行相对第一行缩进 4个空格，从第三行开始，不再继续缩进，参考示例。
   • 运算符与下文一起换行。
   • 方法调用的点符号与下文一起换行。
   • 在多个参数超长，逗号后进行换行。
   • 在括号前不要换行

8. 函数最大行数100行，一个方法内只实现一个功能，方便阅读，尽量减少使用分叉，提高代码覆盖率

9. IDE 的 text file encoding 设置为 UTF-8;IDE中文件的换行符使用 Unix 格式，不要使用 Windows 格式。

（三）常量定义

1. 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中。
2. long或者Long初始赋值时，必须使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。
3. 不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。如：缓存相关的常量放在类：CacheConsts下；系统配置相关的常量放在类：ConfigConsts下。
4. 如果变量值仅在一个范围内变化用Enum类。如果还带有名称之外的延伸属性，必须使用Enum类，下面正例中的数字就是延伸信息，表示星期几。

（四）OOP规约

1. 避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。
2. 所有的覆写方法，必须加@ Override 注解。
3. 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object 。说明：可变参数必须放置在参数列表的最后。
4. 外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@ Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
5. 不能使用过时的类或方法。
6. Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。
7. 所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。
8. 序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败 ； 如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
9. 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
10. 使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
11. 循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展

（五）集合处理

1. 关于 hashCode 和 equals 的处理，遵循如下规则：

   • 只要重写 equals ，就必须重写 hashCode 。
   • 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
   • 如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals

2. ArrayList 的 subList 结果不可强转成 ArrayList ，否则会抛出 ClassCastException异常

3. 使用集合转数组的方法，必须使用集合的 toArray(T[] array) ，传入的是类型完全一样的数组，大小就是 list.size()

4. 使用工具类 Arrays.asList() 把数组转换成集合时，不能使用其修改集合相关的方法，它的 add / remove / clear 方法会抛出 UnsupportedOperationException 异常

5. 不要在 foreach 循环里进行元素的 remove / add 操作。 remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁

6. 在 JDK 7 版本及以上， Comparator 要满足如下三个条件，不然 Arrays.sort ，Collections.sort 会报 IllegalArgumentException 异常。

   • x，y 的比较结果和 y，x 的比较结果相反。
     阿里巴巴 Java 开发手册
     —— 禁止用于商业用途，违者必究—— 11 /35
   • x > y ， y > z ，则 x > z 。
   • x = y ，则 x ， z 比较结果和 y ， z 比较结果相同。

7. 集合初始化时，指定集合初始值大小。

（六）并发处理

1. 获取单例对象需要保证线程安全，其中的方法也要保证线程安全。
2. 创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
3. 线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
4. 线程池不允许使用 Executors 去创建，而是通过 ThreadPoolExecutor 的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。
5. SimpleDateFormat 是线程不安全的类，一般不要定义为 static 变量，如果定义为static ，必须加锁，或者使用 DateUtils 工具类。
6. 高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁 ； 能锁区块，就不要锁整个方法体 ； 能用对象锁，就不要用类锁。
7. 对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
8. 并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用 version 作为更新依据。
9. 多线程并行处理定时任务时， Timer 运行多个 TimeTask 时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用 ScheduledExecutorService 则没有这个问题。

（七）注释规约

1. 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。注释的双斜线与注释内容之间有且仅有一个空格。
2. 所有的抽象方法 （ 包括接口中的方法 ） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
3. 所有的类都必须添加创建者和创建日期
4. 所有的枚举类型字段必须要有注释，说明每个数据项的用途
5. 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可

（八）其他规约

1. 在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
2. 后台输送给页面的变量必须加 $!{var} ——中间的感叹号。
3. 注意 Math . random() 这个方法返回是 double 类型，注意取值的范围 0≤ x <1 （ 能够取到零值，注意除零异常 ） ，如果想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法。
4. 获取当前毫秒数 System . currentTimeMillis(); 而不是 new Date() . getTime();
5. 不要在视图模板中加入任何复杂的逻辑