一、命名规范
1.1 包命名
包名称必须全部用小写。
命名方式:com.业务领域名.业务模块.业务子模块.系统分层
如com.hcepms.proj.ownerunit.dao
com.hcepms.proj.ownerunit.controller
1.2 类命名
类名以英文单词取名,首字母必须大写,多个英文单词以大写字母间隔,避免使用单词的 缩写,除非它的缩写已经广为人知,如HTTP。类名中不允许‘_’、‘-’等符号。
1.3 属性、变量命名
a.定义属性的位置,在类定义的开始,按照public,protected,package,private顺序放置。
b.尽量用相同含义英文单词表示,不允许‘_’、‘-’等符号,如:custName。第一个字母小写,中间单词的第一个字母大写。不要用_或&等符号作为第一个字母。单字符的变量名一般只用于生命期非常短暂的变量。如:i,j,k,m,n一般用于int。如果变量是集合,则变量名应用复数,即以小写s结尾 。
1.4 常量命名
所有常量名均全部大写,单词间以‘_’隔开。例如:MAX_NUM
1.5 方法命名
方法命名采用“动作+属性” 的方法。并且,动作以小写字母开始,属性以大写字母开始。常用的动作有:is、get、set、save、add、del等。
二、编码规范
2.1 类及方法注释
2.1.1 类的注释
目的:主要标注该类的作用,对类进行简单描述;记录类的作者和类的创建日期
/**
* @Description 客户信息实体类
* @author 张三
* @Date 2017年5月18日 下午4:58:07
* @version 1.0.0
*/
public class Customer {
2.1.2 方法的注释
目的:描述该方法的主要意义;对方法的参数进行说明
/**
*
* @Description 根据客户id,查询客户信息
* @param customerId 客户id
* @return 客户信息
* @throws Exception
*/
public Customer getCustomerInfo(String customerId)throws Exception{
2.1.3 变量、属性的注释
目的:描述该属性的意义;对于属性有特殊含义的需要进行特别书面
/**
* 用户姓名
*/
private String name;
或者
//用户姓名
private String name;
2.1.4 代码段注释
目的:行注释是一个非常短的注释,对当前代码片段进行解释说;行尾注释写在该代码块的上面;
格式:
// 用一句话描述下面代码具体的功效
2.1.5 Dao层、Service层接口、实现类的注释说明
Dao层、Service层接口中的方法都必须按照方法的注释要求进行注释
public interface IUserDetailDao extends IBaseDao<UserDetail>{
/**
* 获取组织机构下的人员
* @author 张三
* @time 2016年12月23日 下午5:44:23
* @param page 分页
* @param orgId 组织机构ID
* @return
*/
List<UserImpl> getList(Page page, Long orgId);
/**
* 列表查询
* @author 张三
* @time 2016年12月20日 下午3:58:33
* @param page 分页
* @param content 关键字
* @return
*/
List<UserDetail> getList(Page page, String content);
Dao层、Service层实现类中的方法头部都不需要写注释,但在方法体中,如果写注释进行说明,则用//进行注释说明。
2.1.6 Controller的注释说明
2.1.7 Entity的注释说明
Entity中每一个有意思的属性都要进行说明
public class UserDetail extends BaseEntity implements IUserDetail {
//性别
private String sex;
//备用电子邮箱
private String email;
2.1.7 hibernate.cfg.xml注释说明
把每个模块下的hbm.xml文件放到一块,只进行模块说明,如下
<!-- 工程管理相关业务 -->
<mapping resource="com/hcepms/proj/project/member/entity/projectMember.xml" />
<mapping resource="com/hcepms/proj/ownerunit/entity/ownerUnit.hbm.xml" />
<mapping resource="com/hcepms/proj/laborteam/base/entity/laborTeam.hbm.xml" />
<mapping resource="com/hcepms/proj/laborteam/access/entity/LaborTeamAccess.hbm.xml" />
注:类、方法的注释建议使用eclipse注释模板。
2.2 代码格式
2.2.1 格式缩进
缩进:Tab键的标准占用字符为4个空格字符。
适当内缩后的程式能表现出逻辑结构,并增进可读性,易于理解。
2.2.2 空白行
逻辑上相关序代码与其前后之程序代码间应以空白行加以分隔;在注释段与程序段、以及不同程序段插入空行。
每行只写一条语句。
【说明】适当地使用空白行可以使程序的逻辑结构更清楚,而提高其可读性。
2.2.3 行长度
每行代码最多80个字符
2.2.4 换行规则:当一行或者一个表达式无法在一行内完成,则应该按照如下规则进行换行处理
1)在逗号后换行
2)运算符后换行
3)换行后尽量使表达式排列整齐
4)代码换行后,按照下一行比上一行多4个空字符进行缩进
2.2.5 定义位置:声明变量是应注意位置,至少是在一块代码的开始处(一块代码指的是用”{”和”}”包含的代码块)。不要在使用时才去声明边量,他很容易让人产生混乱,不小心还会引发错误。
2.3 异常处理
在当前的系统架构中,系统自上而下被分为控制器层、业务逻辑层、数据访问层、数据持久层、界面层。本规范约定各层的异常处理机制。
异常处理原则:
1、下层有常异,必须抛向上一层。
2、为了使系统能够更好的跟踪运行情况,必须把底层异常放入新异常中。
3、如果一个层要抛出多个异常,那么所有自定义异常必须统一继承一个父类异常。这样上层可以通过父类异常捕获。
4、异常统一在控制器层处理,控制器层以下的层次在处理异常时,只需要把低层的异常类放到本层约定的异常类中,并抛出,如有需要可以加适当的异常消息。
2.4 对于业务逻辑复杂方法的处理约定
如果一个方法业务逻辑比较复杂,在一个方法中进行处理,该方法将会臃肿、不宜阅读和维护,建议每个方法代码行不要大于50行,建议多使用方法重构。建议对方法中需要进行说明的地方进行注释,如参数、方法中多个步骤的业务逻辑处理。(备注,代码行数指的是代码语句行数,不是编辑器行数)