java web项目开发编码规范

一、命名规范

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{

    /**
     * 获取组织机构下的人员
     * @author 张三
     * @time 2016年12月23日 下午5:44:23
     * @param page  分页
     * @param orgId 组织机构ID
     * @return  
     */

    List getList(Page page, Long orgId);
    /**
     * 列表查询
     * @author 张三
     * @time 2016年12月20日 下午3:58:33
     * @param page      分页  
     * @param content   关键字
     * @return
     */
    List 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行，建议多使用方法重构。建议对方法中需要进行说明的地方进行注释，如参数、方法中多个步骤的业务逻辑处理。（备注，代码行数指的是代码语句行数，不是编辑器行数）

参考：
1、（JAVA技术开发规范（4）——JASMP平台的开发代码规范）
2、J2EE项目开发编码规范