Koala编码规范

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方法，方法必须有对参数的不为空判断