JAVA编码规范

An awesome project.

1 工程

1.1 工程分类

应用分层建议参考阿里巴巴JAVA手册，如图上层依赖于下层，箭头关系表示直接依赖

• 开放接口层： 可直接封装 Service 方法暴露成 RPC 接口;通过Web封装成http接口;进行网关安全控制、流量控制等。
• Web 层： 主要是对访问控制进行转发，各类基本参数校验，或者不复用的业务简单处理等。
• Service层： 相对具体的业务逻辑服务层。
• DAO 层： 数据访问层，与底层 MySQL 、 Oracle 、 Hbase 等进行数据交互。
• 外部接口或第三方平台： 包括其它部门 RPC 开放接口，基础平台，其它公司的 HTTP 接口。

---

2 命名规范

2.1 工程命名

工程命名规则：[解决方案名称]-[工程简写]-[工程类型]。  

解决方案名称一般是产品名的缩写，如afa等，也可以与实际产品业务名称没有任何关联，很多Java开源框架的产品名是动物或者植物的名字，比如tomcat、mongo、ant。
一个产品可能包含很多子系统，或者由前台Web、管理后台、若干服务等子集组成，因此工程命名一般需要加入工程简写。工程简写可以是产品子模块名，例如finance-pay-service，支付pay是财务系统的子功能模块；对于大型产品，工程简写还可以是子系统名，例如oa-hr-web；我们也可以用产品的位置作为工程简写，例如wechat-admin-web、sales-portal-web。
工程类型可以是service、web、job、api、core、client、biz或者不填，不填往往表示独立的jar组件或者pom，如simpson-lisa、simpson-utility、simpson-parent。

2.2 代码命名

好的命名能体现出代码的特征，含义或者是用途，让阅读者可以根据名称的含义快速理清程序的脉络。不同语言中采用的命名形式大相径庭，Java中常用到的命名形式共有三种，既首字母大写的UpperCamelCase，首字母小写的lowerCamelCase以及全部大写的并用下划线分割单词的UPPERCAMELUNSER_SCORE。通常约定，类一般采用大驼峰命名，方法和局部变量使用小驼峰命名，而大写下划线命名通常是常量和枚举中使用。

+ **包命名** 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英文单词或者多个单词自然连接到一块（如 springframework，deepspace不需要使用任何分割）。包名统一使用单数形式，如果类命有复数含义，则可以使用复数形式。 包名的构成可以分为以下几四部分**【前缀】【发起者名】【项目名】【模块名】。** + **类命名** 类名使用大驼峰命名形式，类名通常是名词或名词短语，接口名除了用名词和名词短语以外，还可以使用形容词或形容词短语，如Cloneable，Callable等，表示实现该接口的类有某种功能或能力。对于测试类则以它要测试的类开头，以Test结尾，如HashMapTest。对于一些特殊特有名词缩写也可以使用全大写命名，比如XMLHttpRequest。 + **方法命名** 方法命名采用小驼峰的形式，首字小写，往后的每个单词首字母都要大写。和类名不同的是，方法命名一般为动词或动词短语，与参数或参数名共同组成动宾短语，即动词 + 名词。一个好的函数名一般能通过名字直接获知该函数实现什么样的功能。 + **变量命名** 变量是指在程序运行中可以改变其值的量，包括成员变量和局部变量。变量名由多单词组成时，第一个单词的首字母小写，其后单词的首字母大写，俗称骆驼式命名法（也称驼峰命名法），如 computedValues，index、变量命名时，尽量简短且能清楚的表达变量的作用，命名体现具体的业务含义即可。 常量命名CONSTANT_CASE，一般采用全部大写（作为方法参数时除外），单词间用下划线分割。那么什么是常量呢？常量是在作用域内保持不变的值，一般使用final进行修饰。一般分为三种，全局常量（public static final修饰），类内常量（private static final 修饰）以及局部常量（方法内，或者参数中的常量），局部常量比较特殊，通常采用小驼峰命名即可。

3 代码注解

     好的命名增加代码阅读性，代码的命名往往有严格的限制。而注解不同，程序员往往可以自由发挥，但并不意味着可以为所欲为。优雅的注解通常要满足三要素。
     Nothing is strange 没有注解的代码对于阅读者非常不友好，哪怕代码写的再清楚，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。
     Less is more 从代码维护角度来讲，代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。

• 类注解
       javadoc注解中，每个类都必须有注解。

+ **属性注解**      在每个属性前面必须加上属性注释，通常有一下两种形式，在一个项目中要保持统一。

+ **方法注解**      在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。