请列举至少五种java编程规范_Java编码规范

1    注释规范

1.1   注释的三种形式。

Java语言提供了3种形式的注释

// text      单行注释

/* text */   注释若干行

/** text */  文档注释。注释若干行，并可写入javadoc文档

1.2  类、类属性、类方法的注释必须使用Javadoc规范。

使用/**内容*/格式，不得使用// xxx方式。

说明：在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释；在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

(1)例如：类的注释：

/**

* description: 该文件说明

* @author 张三(张三邮箱)

* @date yyyy-MM-dd HH:mm:ss

* @version 1.0

*/

(2)方法的注释：

/**

* description:

* @author 张三(张三邮箱)

* @date yyyy-MM-dd HH:mm:ss

* @param

* @return

*/

1.3   所有的抽象方法(包括接口中的方法)必须要用Javadoc注释。

除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明：对子类的实现要求，或者调用注意事项，请一并说明。

1.4   所有的类都必须添加创建者和创建日期。

1.5   方法内部单行注释，在被注释语句上方另起一行，使用//注释。

方法内部多行注释使用/* */注释，注意与代码对齐。

1.6   所有的枚举类型字段必须要有注释，说明每个数据项的用途。

1.7   代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

1.8   谨慎注释掉代码。

在上方详细说明，而不是简单地注释掉。如果无用，则删除。

说明：代码被注释掉有两种可能性：

(1)、后续会恢复此段代码逻辑。

(2)、永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉(代码仓库保存了历史代码)。

1.9【参考】对于注释的要求

第一、能够准确反应设计思想和代码逻辑；

第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

1.10【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。

避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

1.11【参考】特殊注释标记，请注明标记人与标记时间。

注意及时处理这些标记，通过标记扫描，经常清理此类标记。

待办事宜(TODO):( 标记人，标记时间，[预计处理时间]) 表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法(因为它是一个Javadoc标签)。

2    命名规范

2.1  命名总体规则

(1)、名字应该能够标识事物的特性，并且与业务挂钩。

(2)、名字使用英文单词，尽量不用拼音，禁止直接使用中文的方式。

(3)、【参考】名字一般由两个或三个单词组成，尽量不要多于四个，控制在3至30个字母以内。

(4)、在名字中，多个单词用大写第一个字母(其它字母小写)来分隔。

(5)、名字均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

2.2  命名概述

以下几点是推荐的命名方法。

(1)、除首字母外，其他单词的首字母大写，其他字母小写

(2)、布尔变量名应该包含 Is，这意味着 Yes/No 或 True/False 值，如 fileIsFound。

(3)、即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。

2.3  缩写

为了避免混淆和保证跨语言交互操作，请遵循有关区缩写的使用的下列规则：

(1)、杜绝完全不规范的缩写，避免望文不知义。

(2)、不要使用计算机领域中未被普遍接受的缩写。

2.4  包

(1)、使用全小写命名。

(2)、一般以com，edu，gov，mil，net，org，等。

(3)、不可含有除英文、数字外的其他字符(“.”除外)，如任何特殊字符“_”，“，”等。

2.5  类

1. 【参考】使用全称避免缩写，除非缩写已是一种公认的约定，如URL、HTML。对于某个命名空间、文件夹下类名中单词都比较长的情况，可以缩写(名字中的关键字不能缩写，其他单词只取首字母)，将所有的缩写做一个说明文件，放在同级目录下。

2. 不使用下划线“_”。

3. 抽象类命名使用Abstract开头；异常类命名使用Exception结尾；测试类命名以它要测试的类的名称开始，以Test结尾。

(1)对于Service和Dao类，实现类用Impl的后缀与接口区别。

- 例如：UserServiceImpl实现UserService接口；UserDaoImpl实现UserDao。

(2)命名规约

- Bean：数据对象，xxxBean，xxx即为数据表名。

- BO(Business Object)：业务对象。由Service层输出的封装业务逻辑的对象。

- VO(Value Object)：返回值对象，通常为各层的返回对象。

- DTO (Data Transfer Object)：数据传输对象 xxxDTO，远程接口入参统一以DTO结尾。

- RE : 远程接口返回值后缀。

- POJO是Bean/DTO/BO/VO/Form等的统称，禁止命名成xxxPOJO。

说明：

1、一般只涉及单表的操作出入参使用xxxBean。以下列举几个可能的业务场景

- 列表页面可直接修改数据

- 一些简单的数据配置查询、修改、详情等功能

2、复杂的页面、功能，通常入参为xxxParam，出参为xxxVO。例如：

- 查询条件较多，已超出单表字段范围。

- 查询条件与列表差异较大。如条件有开始时间、结束时间，但列表只会有一个时间。

3、遇到业务逻辑较复杂的场景，可以在service层创建BO对象，BO对象为包含多个VO对象的复杂对象，尽量不要添加单一的属性(id类属性除外)。

2.6  接口

(1)、不使用下划线“_”。

(2)、【推荐】 如果是形容能力的接口名称，取对应的形容词做接口名(通常是–able的形式)。

正例：AbstractTranslator实现 Translatable。

2.7  枚举(Enum)

(1)、命名建议带上Enum后缀。  统一用包装类

(2)、枚举成员名称需要全大写，单词间用下划线隔开。

说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例：枚举名字为ProcessStatusEnum的成员名称：SUCCESS / UNKOWN_REASON。

2.8  参数

参数名称一般以参数类型名称命名，或是类型名称中的某几个单词，或是单词缩写。

2.9  方法

* 以动词开头。

* 尽量避免缩写。

* 不使用下划线“_”。

1、Service/Dao层方法命名规约 ：

1) 获取单个对象的方法用get做前缀。 参考：getXXX()

2) 获取多个对象的方法用get做前缀,以List标明结果为多条。

参考：getXXXList  getXXXListById

3) 获取统计值的方法用get做前缀，以Count标明统计值。

参考：getXXXCount getXXXCountById

4) 插入的方法用insert做前缀。 批量插入用insertBatch做前缀。

5) 逻辑删除的方法用delete做前缀。物理删除的方法用remove做前缀(理论上禁止物理删除)。

6) 修改的方法用update做前缀。(仅Dao层限制)

备注：当且仅当根据单个条件去执行操作的方法，方法名后缀为ByXXX。根据两个或多个条件去执行操作的方法不加ByXXX。

参考：getUserById getUserListById deleteUserById updateUserById

2、Service层推荐方法名前缀：

check   convert calculate init format exec invoke match compare join

process filter split add  copy clone ……

2.10  属性

(1)、以名词或形容词命名。

(2)、不使用下划线“_”。

2.11  变量

(1)、变量名不应以下划线或美元符号开头。

(2)、long或者Long初始赋值时，使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。

(3)、按作用域定义

2.12  常量(const)

全部大写，单词间以“_”分隔，力求语义表达完整清楚，不要嫌名字长。

常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。

(1)、跨应用共享常量：放置在client包中，通常是常量所属的项目对应包中的constant目录下。

(2)、应用内共享常量：放置在本应用中，通常是common中的constant目录下。

(3)、子工程内部共享常量：即在当前子工程的constant目录下。

(4)、包内共享常量：即在当前包下单独的constant目录下(如果该包下没有子包，则常量类直接方法该包下即可)。

(5)、类内共享常量：直接在类内部private static final定义。

2.13  静态变量

(1)、变量名不应以下划线或美元符号开头。

(2)、建议全部大写，单词间以“_”分隔。

2.14  集合

变量名使用复数。

2.15  范型

以一个大写字母(建议优先使用T)表示类的类型，以一个小写字母(如：t)表示类名。

3  编码规则

3.1  文件编码规则

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

3.2  缩进规则

采用 4 个空格缩进，禁止使用 tab 字符。
    说明： 如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。 IDEA 设置 tab 为 4 个空格时，请勿勾选 Use tab character；而在 eclipse 中，必须勾选 insert spaces for tabs。

3.3  换行规则

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

1) 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进。

2) 运算符与下文一起换行。

3) 方法调用的点符号与下文一起换行。

4) 方法调用时，多个参数，需要换行时，在逗号后进行。

5) 在括号前不要换行。

3.4  空格规则

任何二目、 三目运算符的左右两边都需要加一个空格。 说明： 运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

注释的双斜线与注释内容之间有且仅有一个空格。

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

3.5  空行规则

方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义
之间插入一个空行。相同业务逻辑和语义之间不需要插入空行。

注释与它注释的语句间不空行，但与其他的语句间空一行。

文件之中不得存在无规则的空行，比如说连续十个空行。空行是为了将逻辑上相关联的代码分块，以便提高代码的可阅读性。

3.6  大括号规则

如果是大括号内为空，则简洁地写成{}即可，不需要换行；

如果
是非空代码块则：

1) 左大括号前不换行。

2) 左大括号后换行。

3) 右大括号前换行。

4) 右大括号后还有 else 等代码则不换行； 表示终止的右大括号后必须换行。

例如：

if  (expression) {

}

3.7  小括号规则

左小括号和字符之间不出现空格； 同样，右小括号和字符之间也不出现空格。

if/for/while/switch/do 等保留字与括号之间都必须加空格。

3.8  模块化规则

某一功能，如果重复实现一遍以上，即应考虑模块化，将它写成通用函数。并向小组成员发布。同时要尽可能利用其它人的现成模块。

4  异常日志

4.1  异常处理

1. 【强制】异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。

2. 【强制】对大段代码进行try-catch，这是不负责任的表现。catch时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理。

3. 【强制】捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

4. 【强制】有try块放到了事务代码中，catch异常后，如果需要回滚事务，一定要注意手动回滚事务。

5. 【强制】finally块必须对资源对象、流对象进行关闭，有异常也要做try-catch。

6. 【强制】不能在finally块中使用return，finally块中的return返回后方法结束执行，不会再执行try块中的return语句。

7. 【强制】捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。

说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

8.    【推荐】方法的返回值可以为null，不强制返回空集合，或者空对象等，必须添加注释充分说明什么情况下会返回null值。调用方需要进行null判断防止NPE问题。

说明：本手册明确防止NPE是调用者的责任。即使被调用方法返回空集合或者空对象，对调用者来说，也并非高枕无忧，必须考虑到远程调用失败、序列化失败、运行时异常等场景返回null的情况。

5  远程服务规范

5.1  远程服务类

项目提供的远程服务类统一放在本项目的remote/client包下，远程方法名称必须和服务名中的方法名一致。

5.2  服务命名

RPC + 项目名称 + 功能 + Remote + Service。

比如 RpcVenusOrderRemoteService

5.3  入参

为保证服务后续扩展和属性描述规范，一律使用DTO对象进行传输。

每个服务使用专用DTO,不得复用。

DTO内部属性命名规则同数据库命名规则并写全属性注释。

5.4  返回结果

为保证后续服务扩展和属性描述规范，一律使用Result对象进行传输，Result对象中包含业务消息主体建议以Re结尾。

每个服务使用专用Re，不得复用。

所有RE和对应的DTO放在同一包下。

Result对象包含协议属性：

date:    业务正常返回的消息体,每个服务使用专用Re对象，不可复用。属性命名规则同数据库命名。

status: 服务状态码，为int类型，0 为成功，-1为业务异常，-2为服务异常。

code:   业务语义状态码，用于做业务语义路由。

msg:    描述信息。用于返回业务异常信息和服务异常信息，不可用于设置日志堆栈信息。