dangerwolf/编码规范.md

#JAVA开发规范

[TOC]

##开发环境

###开发工具

开发人员统一使用Eclipse 或 MyEclipse进行开发，项目工程使用maven工程。

###JDK版本

使用JDK1.7，对小版本暂时没有要求。

###Tomcat

使用Tomcat 7.0.69，或其以上的版本。

###数据库

Oracel 11g 、SqlServer2008、MySql 5.6。

##命名

命名规范使得程序更易读，从而使得程序更容易理解。它可以给我们关于标识符功能的信息（如，标识符是一个常量、包还是类），从而帮助我们理解代码。

###命名的一般概念

使用有意义的单词，且避免使用单个字符或者一些泛泛的单词作为名字（临时变量除外）
尽量使用完整的英文描述符
采用适用于相关领域的术语(ehr的专业词汇见附录)
采用大小写混合使名字可读
尽量少用缩写，但如果用了，要明智地使用，且在整个工程中统一(ehr的缩写规范见附录)
避免使用长的名字（小于 24 个字母是个好主意）
避免使用类似的名字，或者仅仅是大小写不同的名字
避免使用下划线（除静态常量等）

类文件名

当命名一个类时，请遵守以下规则：

对于组成类名的每一个单词的首字母都应当大写；
类名应当由名词组成。应当尽量使类名简单且容易理解。各个名词应使用全称而避免使用缩写词（acronyms and abbreviations），除非缩写形式比原词本身的应用更广，如URL或HTML；
- 如果一个类是一些相关的属性（attributes）、静态服务（static services，静态方法）或常量（constants）的集合，那么类名应当使用名词的复数形式；
类名由大写字母开头；
对于单元测试类，以Test开头。例如：TestAddEmployee

###接口文件名

接口名与类名基本相同，对于组成接口名的每一个单词的首字母都应当大写，接口名应当是一个名词或形容词。名词是对接口提供服务的描述。例如：

public interface ActionListener {
    public void actionPerformed(ActionEvent e);
}

形容词是对接口能力的描述。许多描述具有某种能力的接口其名字都使用在动词后加上“able”或“ible”后缀的方式。例如：

public interface Runnable {
    public void run();
}
public interface Accessible {
    public Context getContext();
}

###Java包文件命名

当命名一个包时，请遵守以下规则：

使用逆序的、全小写的组织的 Internat 域名作为包名开始的限定符,比如商业的应用使用com,开源的使用org等
使用单一的小写单词作为每个包的开始。该单词应当可以准确、清晰的表示这个包的作用
对于一个包的新版本，如果其对原版本保持兼容，则使用原有的包名。否则，使用一个新名字
命名的规则:域名+公司英文简写名+产品英文简写名+子系统英文简写名+模块英文简写名

例如,我们通辽集控系统管理模块的包可以命名为:com.neusoft.tljk.system。

###Jsp文件命名规范

Jsp 文件的命名应尽量描述 Jsp文件本身的含义，可以由多个英文单词构成，第一个单词的开头字母小写，其它单词的开头字母要大写，如 setDisplayOrder.jsp，由三个单词组成 set、display、order，第一个单词的开头字母小写，其它单词的开头字母都大写。

jsp文件命名以英文的动词+名次组合，动词代表功能工作，名词为要操作的对象；
jsp文件名称的第一个单词小写，以后每个单词第一个字母大写，其它每个字母小写，如editUser.jsp；
对于命名中的动词，约定如下：

新建/添加：add；编辑/修改：edit；删除：delete；激活/启用：permit；作废/禁用：forbid；查询选项页面：search；查询结果列表：list；查看单条记录的详细信息：view；如果页面是添加修改公用：addEdit（如果隐含查看功能，则不单独表示）；公共的选择业面：select；如选择岗位的公共页面，selectJobs.jsp。

###Java语言命名规范

####方法名

方法名应当遵守以下规则：

以英文的动词+名次组合，动词代表功能动作，名词为要操作的对象；
第一个单词小写，以后每个单词第一个字母大写，其它字母全部小写，如addUser（）；
对于命名中的动词，约定如下：

新建/添加：add；更新/修改：update；删除：delete；添加、修改、删除的任意组合：save；维护/管理：manage；设置：set；查询列表：list；（返回结果通常为List）检查满足条件的一个对象是否已经存在，用findXXX,返回布尔值；得到单条记录中的一个属性：get；因为输入参数的不同，还可以这样命名方法，如getXXXByID，getXXXByCode等。

    例如：
    添加用户：addUser
    更新用户：updateUser
    删除用户：deleteUser
    添加、删除、修改用户结果的统一保存：saveUser
    管理用户：manageUser
    设置用户状态：setStatus
    查询用户列表：listUsers
    判断一个用户是否存在：findUser
    通过ID获得一个用户的详细信息：getUserByID
    得到用户的一个属性：getStatus

####变量名

变量名应当遵守以下规则：

对于组成变量名的各个单词：第一个单词全部小写；后面的每个单词的首字母大写，其余字母小写,如用户名：userName。
使用名词命名变量。
对于对象集合的引用，其名称应当使用名词的复数。
循环变量：尽量使用明确含义的变量。对于逻辑简单的部分，可以使用i, j, k, l。
临时变量的常用名称如下：

类型	常用名
Character	c, d, e
Coordinate	x, y, z
Exception	exName
Graphics	gName
Object	objName
Stream	inName, outName, inOutName
Strin	strName

使用“this”来区分实例字段（instance field）和方法的参数。

####常量名

组成常量名的每个单词全部大写，且使用下划线“_”分隔单词。尽量不要在代码中使用-1, 0, 1以外的含有意义的数字(Magic Number)，而要使用常量来代替。

例如，状态有效：STATUS_VALID

##注释

注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息

###注释规则

注释率：规定每个Java文件的注释率要达到25％以上；
注释方法：使用Eclipse注释模板。在新建java文件的时候，eclipse会自动按照模版的定义生成java文件的头注释和类的javadoc注释。添加方法和成员变量的注释的时候，可以使用快捷键Alt+Shift+J。关于注释模板的导入方法见后；
注释语言：可以使用中文进行代码注释。

###Java文件头注释

所有的源文件开头都必须有一个的文件头注释，其中列出了版本信息和文件名。

/*	
 * Web 5.0 Copyright 2016 Aptech, Co.ltd. All rights reserved.
 * 		 
 * FileName: SysUserService.java
 *
 */

###类的JavaDoc注释

说明该类的含义和作用。包含以下信息：该类的含义及作用，对于较复杂的类需要说明类的使用方法；创建时间；作者；最后修改时间；修改历史。

关于修改历史，下面给出了书写规范，统一按照这个格式进行书写。

/**
 * {该处请说明该class的含义和作用}
 * 
 * @author user
 * @created 2010-6-30 下午06:24:38
 * @lastModified 
 * @history  
 *       2010-6-30 mazt 修正方法xxxx
 *       2010-6-30 mazt 新增方法yyyy
 *
 */

###方法的JavaDoc注释

说明该方法的含义、作用及使用方法。包含如下信息：该函数的含义、作用，对于复杂的函数需说明该函数的使用方法；该函数返回值的说明，对于复杂的返回对象，需说明其结构；该函数使用参数的含义和作用，对于复杂的参数需说明该参数的结构；该构造函数抛出的异常的含义和作用；创建时间；作者；最后修改时间。

/**
 * {该处请说明该method的含义和作用}
 * 
 * @param
 * @return
 * @throws
 * @author
 * @created
 * @lastModified
 */

###构造方法的注释

同方法的javadoc注释。

###成员变量的注释

说明该变量的含义及作用。包括：该变量的含义和作用。

/**
 * {该处请说明该成员变量的含义和作用}
 */

###方法内的注释

方法块内声明，说明函数块内各部分重要变量或复杂的代码结构的说明，使用//作为注释标记。在方法内代码的逻辑块之间增加空行以提高可读性。

public String a(String a) throws Exception {

	// 步骤1的处理说明，使用变量的说明
	……
    ……

	// 步骤2的处理说明，使用变量的说明
	……
    ……

	return a;
}

每一个逻辑判断都要有注释。例如：

// 页面用户名称的非空检查
if(StringUtils.isNullString(strUserName)) {
	// 如果没有输入用户名称,抛出业务异常
	throw new TestDCException();
} else {
	// 如果没有输入用户名称,保存到数据库
	TestDCDAO.saveUserName(strUserName);
}

###一些建议

类400行（小于1000行），方法80行，行长度120字符。

#数据库设计规范

##数据库表名

业务模块表名应遵守以下规则：统一使用'TB_模块缩写_'作为表的前缀，前缀后面加表的名称；

例如：计算平台模块表名： TB_CAL_XXXX_XXXX。
平台表名应遵守以下规则：统一使用’ TP_{$ModuleName}_’作为表的前缀，前缀后面加表的名称，其中{$ ModuleName }代表各自的模块名称。

例如：TP_SYS_USER

说明：

使用单数名词或者用“_”分隔的单数名词组合作为表名，单数名词组合不能超过3个单词;
该名词或名词组合要准确、清晰的表示这个表的作用;
所有字母大写，表名长度不能超过32个字符;
每个名词应该尽量避免使用缩写，如果确实需要使用过长的名词，可以适当使用缩写，但要确保缩写的含义利于理解.

##表字段名

字段名应遵守以下规则：

统一使用'C_'作为字段名的前缀，前缀后面加上字段的名称信息

例如：C_XXX_XXX。

说明：

使用单数名词或者用“_”分隔的单数名词组合作为字段名, 单数名词组合不能超过3个单词;
该名词或名词组合要准确、清晰的表示这个字段的作用;
所有字母大写，字段名长度不能超过 30 个字符;
每个名词应该尽量避免使用缩写，如果确实需要使用过长的名词，可以适当使用缩写，但要确保缩写的含义利于理解.

保证字段名的一致性

主键中文名称统一命名为'主键'，英文名称统一命名为'C_ID’;
对于数据有效性控制的生效日期和生效截止日期字段，生效日期统一英文名为'C_BEGIN_DATE',生效截止日期统一英文名为'C_END_DATE'，此两个字段为数据有效性控制的专用字段;
对于有编码字段的数据库表，编码字段统一中文名称为'XX编码'，英文名称为'C_CODE';
对于有名称字段的数据库表，名称字段统一中文名称为'XX名称'，英文名称为'C_NAME'；特殊情况，如人员的姓名使用通常的习惯，命名为'XX姓名';
对于使用其他表的主键作为外键的数据库表，其作为外键的字段中文名统一命名为'XX 编号'，英文名称统一命名为引用的表名去掉前缀加'ID';

例如：表TB_SYS_USER引用表TB_SYS_UNIT的主键字段C_ID作为外键，那么这个字段中文名称为'组织机构ID'，英文名称为'C_UNIT_ID'。
对于有记录状态的数据库表，记录状态字段统一命名为'C_STATUS';
对于时间类型的字段，如果只需要精确到天，中文名称统一命名为'XXX日期'，英文名称统一命为'C_XXX_DATE'，特殊情况如人员的出生日期，使用通常的习惯C_XXX_BIRTHDAY'；如果需要精确到小时乃至分钟、秒，中文名称统一命名为'XXX时间'，英文名称统一命名为'C_XXX_TIME'。

例如：员工入司的日期，只需要精确到天，中文名称为'入司日期'，英文名称为'C_ENTRY_DATE'；应聘者的面试时间，需要精确到分钟，中文名称为'面试时间'，英文名称为'C_INTERVIEW_TIME'。
状态和类型的差别是状态不同指的是同一个事物带有不同的属性，而类型不同指的是不同的事物。对于中文名称为'XXX状态'的字段，英文名称统一命名为'C_XXX_STATUS'；对于中文名称为'XXX类型'的字段，英文名称统一命名为'C_XXX_TYPE';

dangerwolf/编码规范.md

Select an option

No results found

Select an option

No results found

类文件名