Koala编码规范

1 前言

本文档是Koala项目编程风格规范的完整定义，项目模块源文件必须符合本文档设定的规则。

与其它的编程风格指南一样，这里所讨论的不仅仅是编码格式美不美观的问题， 同时也讨论一些约定及编码标准。

2 源文件

2.1 文件编码：UTF-8

2.2 命名：大写字母开头，驼峰式，只允许英文

2.3 文件结构按照顺序如下表所示：

元素 要求

1，许可证或版权信息

2，package语句 package语句不换行

3，import语句 不能使用通配符

4，一个顶级类

注：以上每个元素之间用一个空行隔开。

2.4 约定：

• 代码必须格式化
• 不能出现黄色提示
• 类、方法必须写注释
• 类和方法级的说明需要句号，参数和返回就不需要（示例如下表）
• 代码保持清洁（不能留用//注释的代码等）

示例
/**
 * 抽象实体类，可作为所有领域实体的基类。
 *
 * @author yang
 *
 */
@MappedSuperclass
public abstract class BaseEntity implements Entity {

/**
     * 获取仓储对象实例。如果尚未拥有仓储实例则通过InstanceFactory向IoC容器获取一个。
     * @return 仓储对象实例
     */
    public static EntityRepository getRepository() {
        if (repository == null) {
            repository =
 InstanceFactory.getInstance(EntityRepository.class);
        }
        return repository;
    }

}

3 命名规范

命名的关键要素是简短、意图清晰，遵守下面表格规则：

元素        
要求                                                              
示例

1. 项目模块 只能使用小写字母和中划线，以中划线分割单词 koala-security-core
2. 包 只能使用小写字母 org.openkoala.security.core.domain
3. 类 只能使用大小写字母，大驼峰式 EntityRepository.java
4. 字段 只能使用大小写字母和下划线，小驼峰式 private String userAccount
5. 方法 只能使用大小写字母，小驼峰式 findChildrenOfOrganization
6. URL 只能使用小写字母和中划线 employee/get-posts-by-employee.koala
7. JS、CSS、JSP 只能英文、数字和中划线

4 模块约定

4.1领域层

? 包命名格式xxx.xxx.core.domain，例org.openkoala.security.core.domain

? 异常类放在xxx.xxx.core下，以xxxException结尾，必须是RuntimeException的子类

? JPA实体表、列名必须大写，以下划线分割，其中表名需是复数（例：KO_ACCOUNTABILITIES）

? JPA实体内容编写顺序，字段->构造函数->方法(动->静)->业务主键->属性

? 查询方法实现使用命名查询和CriteriaQuery查询对象，简单查询使用CriteriaQuery实现较快

? JPA实体的方法必须编写相对应的单元测试，并且有较高的覆盖率

4.2应用层

? 包命名格式xxx.xxx.application，例org.openkoala.security.application

? 接口必须编写详细的注释

? 接口方法必须编写相对应的单元测试，并且有较高的覆盖率

4.3门面层

? 包含fa?ade接口和DTO对象

? 包命名格式xxx.xxx.facade，例org.openkoala.security.facade

xxx.xxx.facade.dto，例org.openkoala.security.facade.dto

? 命令接口返回InvokeResult对象，查询接口返回Page对象，获取数据接口直接返回

? pom文件不能有任何技术依赖

4.4门面实现层

? 包含fa?ade接口实现和assembler装配器

? 包命名格式xxx.xxx.facade.impl，例org.openkoala.security.facade.impl

xxx.xxx.facade.impl.assembler，例org.openkoala.security.facade.impl.assembler

? Assembler类必须包含toEntity和toDTO方法，方法必须有对参数的不为空判断