Java 开发规范.docx
《Java 开发规范.docx》由会员分享，可在线阅读，更多相关《Java 开发规范.docx（17页珍藏版）》请在冰豆网上搜索。
Java开发规范
Java开发规范
绪论
绪论
目的
本规范的目的是使本组织能以标准的、规范的方式设计和编码。
通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。
参考资料
《Java编程指南》见RUP（RationalUnifiedProcess）中文版。
《Java技术手册》（JavainaNutshell）
《SunJava语言编码规范》（JavaCodeConventions）
《EffictiveJava》
《JavaPitfalls》
《JavaRules》
概述
对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。
然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。
因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。
最根本的原则：
代码虽然是给机器运行的，但却是给人读的！
代码组织与风格
1.
2.
基本原则
代码的组织和风格的基本原则是：
便于自己的开发，易于与他人的交流。
操作指南
代码的组织格式直接采用Eclipse内建的Formatter格式，使用Format功能组织文件即可。
注释
基本原则
1.
2.
3.
●注释应该增加代码的清晰度。
代码注释的目的是要使代码更易于被其他开发人员理解。
●如果你的程序不值得注释，那么它很可能也不值得运行。
●避免使用装饰性内容。
●保持注释的简洁。
●注释信息不仅要包括代码的功能，还应给出原因。
●不要为注释而注释。
●除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
JavaDoc注释操作指南
对类/接口、非私有方法、非私有变量等的注释必须使用JavaDoc注释。
操作指南：
1）导入注释模版
为Eclipse所有工程导入注释模版：
a）菜单Window->Preferences，Java->CodeStyle->CodeTemplates；
b）用Import命令导入附录1中的Eclipse代码注释模板文件。
为Eclipse单个工程导入注释模版：
a）菜单Project->Properties，JavaCodeStyle->CodeTemplates；
b）用Import命令导入附录1中的Eclipse代码注释模板文件。
2）编写Java类/接口时，在类/接口、非私有方法、非私有变量的上一行用/**前导并回车可自动产生JavaDoc注释的格式，将%x%修改为实际的内容。
3）在非私有方法的JavaDoc注释的补充说明
一般有参数有返回值有异常的方法自动生成的注释类似如下（不包括红色字体的内容）：
/**
*
*%方法的一句话概述（注：
句号不能删除，本注应删除）%。
*
%方法详述（简单方法可不必详述）%
*@params说明参数含义
*@return说明返回值含义
*@throwsIOException说明发生此异常的条件
*@throwsNullPointerException说明发生此异常的条件
*/
默认生成的JavaDoc注释没有这些红色字体的内容，它们必须被填入实际内容，才能产生优美格式的JavaDoc文档。
其他
以下情况必须添加注释：
Ø私有方法，除构造函数外，必须添加该方法的注释（JavaDoc注释或非JavaDoc注释均可）。
Ø复杂方法（如方法体超过30行），或包含关键算法的方法，必须对内部的操作步骤添加注释（行注释//或块注释/**/均可）。
Ø方法内部多次转换含义的变量，必须对该变量的含义发生变化时添加注释。
Ø方法内部存在不易理解的多个分支条件的表达式，必须对每个分支添加注释。
Ø对于引入的工程外、非Java内建类库的、不常见的包与类，在行末或上一行添加行注释。
Ø重要的包，必须添加注释。
以下情况可不必添加注释：
⏹PO类的属性（私有变量），由于已经在get/set方法内添加JavaDoc注释，因此可不必添加。
⏹构造函数。
配置文件注释
非项目自有的应用或包的配置文件内增加新参数，或者需要维护人员修改的参数，必须增加注释，注释内容包括：
含义，默认值，设置范围。
项目自有的配置文件，必须为每个参数增加注释，注释内容包括：
含义，默认值，设置范围。
命名
1.
基本原则
规范的命名能使程序更易阅读，从而更易于理解。
它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。
●使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。
例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，尽量不使用汉语拼音及不相关单词命名，严禁使用汉语拼音首字母组合命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。
●采用该领域的术语。
如果用户称他们的“客户”（clients）为“顾客”（customers），那么就采用术语Customer来命名这个类，而不用Client。
●采用大小写混合，提高名字的可读性。
一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。
包名全部小写。
●避免使用长名字（最好不超过25个字母）。
●避免使用相似或者仅在大小写上有区别的名字。
●避免使用数字，但可用2代替to，用4代替for等，如：
go2Jsp。
文件、包
●文件名当与其类严格相同，所有单词首字母大写。
●包名一般以项目或模块名命名，少用缩写和长名，一律小写。
●基本包：
com.aspire，所有包、文件都从属于此包。
●包名按如下规则组成：
[基本包].[项目名].[模块名].[子模块名]...
如：
com.aspire.quasar
com.aspire.dao.oracle
●不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目
和模块包中。
类、接口
所有单词首字母大写。
使用能确切反应该类、接口含义、功能等的词。
一般采用名词。
接口可带I前缀或able、ible、er等后缀。
字段
●常量
采用完整的英文大写单词，在词与词之间用下划线连接，如：
DEFAULT_VALUE
●变量和参数
对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用
strXXX,boolean使用isXXX，hasXXX等等。
除第一各个单词外其余单词首字母大写。
对私有实例变量可使用_前缀，但在其存取方法中则应该将其前缀去掉。
●组件/部件
应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则
如：
btnOK，lblName。
●集合
一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。
命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。
如：
VectorvProducts=newVector（）;//产品向量
ArrayaryUsers=newArray（）;//用户列表
●神秘的数
在程序里经常会用到一些量，它是有特定的含义的。
例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。
在这里，50就是"神秘的数"。
当别的程序员在程序里看到50这个数，将很难知道它的含义，造成理解上的困难。
在程序里出现"神秘的数"会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类"神秘的数"。
避免的方法是把神秘的数定义为一个常量。
注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。
例如上面50这个数，我们可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。
这样，别的程序员在读程序的时候就可以容易理解了。
●其他
命名时应使用复数来表示它们代表多值（数组）。
如：
orderItems。
方法
方法的命名应采用完整的英文描述符，大小写混合使用：
所有中间单词的第一个字母大写。
方法名称的第一个单词常常采用一个有强烈动作色彩的动词。
类中常用方法的命名：
1.类的获取方法（一般具有返回值）一般要求在被访问的字段名前加上get，如
getFirstName（），getLastName（）。
2.类的设置方法（一般返回类型为void）：
被访问字段名的前面加上前缀set，如
3.setFirstName（）,setLastName（）.
4.类的布尔型的判断方法一般要求方法名使用单词is做前缀，如isPersistent（）isString（）。
或者使用具有逻辑意义的单词，例如equal或equals。
5.类的普通方法一般采用完整的英文描述说明成员方法功能，第一个单词尽可能采用动词，首字母小写，如openFile（），addCount（）。
6.构造方法应该用递增的方式写。
（参数多的写在后面）。
7.toString（）方法：
一般情况下，每个类都应该定义toString（）,其格式为：
publicStringtoString（）{…}。
异常
异常类名由表示该异常类型的单词和Exception组成，如ActionException。
异常实例一般使用e、ex等，在多个异常时使用该异常名或简写加E，Ex等组成，如：
SQLExActionEx
声明
2.
基本原则
声明的基本原则是遵守Java语言规范，并遵从习惯用法。
包
在导入包时当完全限制代码所使用的类的名字,尽量少用通配符的方式，但导入一些通用包，或用到一个包下大部分类时，则可是使用通配符方式，如：
importcom.aspire.quasar.services.Service;
importjava.util.*;
同一包中的类导入时当声明在一起，可由编辑器自动完成此功能。
重要的包当添加注释。
类、接口
类、接口定义语法规范：
[可见性][（'abstract'|'final'）][Class|Interface]class_name
[（'extends'|'implements'）][父类或接口名]{
}
如：
publicclassLoginActionextendsBaseActionimplemnetsActionListener{
}
方法
良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：
尽量限制成员函数的可见性。
如果成员函数没必要公有（public），就定义为保护（protected）；没必要保护
（protected），就定义为私有（private）。
方法定义语法规范：
[可见性][（'abstract'|'final'）]['synchronized'][返回值类型]method_name（参数
列表）[（'throws'）][异常列表]{
//功能模块
}
如：
publicListlistAllUsers（）throwsDAOException{
}
若有toString（）,equals（）,hashCode（）,colone（）等重载自Object的方法，应将其放在类的最后。
声明顺序：
构造方法
静态公共方法
公共方法
静态私有方法
受保护方法
私有方法
继承自Object的方法
字段
字段定义语法规范：
[（‘public’|’private’|’protected’）]
[（‘final’|’volatile’）][‘static’][‘transient’]
data_typefield_name[‘=’expression]‘;’
若没有足够理由，不要把实例或类变量声明为公有。
公共和保护的可见性应当尽量避免，所有的字段都建议置为私有，由获取和设置成员函数（Getter、Setter）访问。
不允许“隐藏”字段，即给局部变量所取的名字，不可与另一个更大范围内定义的字段的名字相同（或相似）。
例如，如果把一个字段叫做firstName，就不要再生成一个局部变量叫做firstName，或者任何易混肴的名字，如fistName。
数组声明时当将"[]"跟在类型后，而不是字段名后，如：
Integer[]ai=newInteger[2];//一个整数对象数组，用于...
Integeraj[]=newInteger[3];//不要用这种数组声明方式
一行代码只声明一个变量，仅将一个变量用于一件事。
声明顺序：
常量
类变量
实例变量
公有字段
受保护字段
私有字段
可以将私有变量声明在类或接口的最后。
注意受保护变量、私有变量、“包”变量间的区别。
类与接口
3.
基本原则
类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。
一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User来存放用户信息，而用UserDAO来对用户信息进行数据访问操作（比如存取数据库），用UserBroker来封装用户信息的业务操作等等。
多使用设计模式，随时重构。
多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。
将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。
将不希望被实例化的类的缺省构造方法声明成private。
抽象类与接口
一般而言：
接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java集合等实现。
多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。
继承与组合
尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。
尽量避免在深度继承的类的构造函数中建立对象。
构造函数和静态工厂方法
当需要使用多个构造函数创建类时，建议使用静态工厂方法替代这些构造方法（参考《EffictiveJava》Item1），例如：
publicclassUser{
publicUser（）{
super（）;
//dosomethingstocreateuserinstance
}
publicstaticUsergetInstance（Stringname,Stringpassword）{
Useru=newUser（）;
u.setName（name）;
u.setPassword（password）;
returnu;
}
方法
4.
基本原则
一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。
避免用一个类是实例去访问其静态变量和方法。
避免在一个较长的方法里提供多个出口：
//不要使用这钟方式，当处理程序段很长时将很难找到出口点
if（condition）{
returnA;
}else{
returnB;
}
//建议使用如下方式
Stringresult=null;
if（condition）{
result=A;
}else{
result=B;
}
returnresult;
参数和返回值
避免过多的参数列表，尽量控制在5个以内，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性。
参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高系统的可扩展性，例如：
publicvoidjoinGroup（ListuserList）{}
publicListlistAllUsers（）{}
表达式与语句
5.
基本原则
表达式和语句当清晰、简洁，易于阅读和理解，避免使用晦涩难懂的语句。
每行至多包含一条执行语句，过长当换行。
避免在构造方法中执行大量耗时的初始化工作，应当将这中工作延迟到被使用时再创建相应资源，如果不可避免，则当使用对象池和Cache等技术提高系统性能。
避免在一个语句中给多个变量赋相同的值。
它很难读懂。
不要使用内嵌（embedded）赋值运算符试图提高运行时的效率，这是编译器的工作。
尽量在声明局部变量的同时初始化。
唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。
一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。
即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。
你不能假设别的程序员和你一样清楚运算符的优先级。
不要为了表现编程技巧而过分使用技巧，简单就好。
控制语句
判断中如有常量，则应将常量置于判断式的右侧。
如：
if（true==isAdmin（））...
尽量不使用三目条件的嵌套。
所有if语句必须用{}包括起来,即便是只有一句：
if（true）{
//dosomething......
}
if（true）
i=0;//不要使用这种
当有多个else分句时当分别注明其条件，注意缩进并对齐，如：
//先判断i是否等于1
if（i==1）{//if_1
//.....
}//然后判断i==2
elseif（i==2）{
//i==2说明。
。
。
。
。
。
j=i;
}//如果都不是（i>2||i<1）
else{
//说明出错了
//....
}//endif_1
过多的else分句请将其转成switch语句或使用子函数。
每当一个case顺着往下执行时（因为没有break语句），通常应在break语句的位置添加注释。
如：
switch（condition）{
caseABC:
//statements;
//继续下一个CASE
caseDEF:
//statements;
break;
caseXYZ:
//statements;
break;
default:
//statements;
break;
}//endswitch
循环语句
循环中必须有终止循环的条件或语句，避免死循环。
当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。
若需要，可以在for循环之前（为初始化子句）或for循环末尾（为更新子句）使用单独的语句。
因为循环条件在每次循环中多会执行一次，故尽量避免在其中调用耗时或费资源的操作，比较一下两种循环的差异：
//不推荐方式____________________________________________
while（index//每此都会执行一次getCount（）方法，
//若此方法耗时则会影响执行效率
//而且可能带来同步问题，若有同步需求，请使用同步块或同步方法
}
//推荐方式______________________________________________
//将操作结构保存在临时变量里，减少方法调用次数
finalintcount=products.getCount（）;
while（index}
异常处理
6.
基本原则
●通常的思想是只对错误采用异常处理：
逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。
●通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。
●最小化从一个给定的抽象类中导出的异常的个数。
对于经常发生的可预计事件不要采用异常。
不要使用异常实现控制结构。
●确保状态码有一个正确值。
●在本地进行安全性检查，而不是让用户去做。
●若有finally子句，则不要在try块中直接返回，亦不要在finally中直接返回。
已检查异常与运行时异常
已检查异常必须捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。
对可预见的运行时异常当进行捕捉并处理，比如空指针等。
通常，对空指针的判断不是使用捕捉NullPointException的方式，而是在调用该对象之前使用判断语句进行直接判断，如：
//若不对list是否为null进行检查，则在其为null时会抛出空指针异常
if（null!
=list&&0for（inti=0;i}
}
建议使用运行时异常（RuntimeException）代替已检查异常（CheckedException）。
异常的捕捉与处理
1.异常的控制范围
在数据访问层产生的Sql异常，均向上抛出，由业务层处理。
在业务层捕获本层以及数据层的所有异常，并处理。
不将异常抛到表现层。
2.多个异常应分别捕捉并处理，避免使用一个单一的catch来处理。
如：
try{
//dosomething
}catch（IllegalStateExceptionIllEx）{
IllEx.printStackTrace（）;
//dealwithIllEx
}catch（SQLExceptionSQLEx）{
SQLEx.printStackTrace（）;
throwSQLEx;//抛给调用者处理
}finally{
//释放资源
}
字符串资源国际化
基本原则
字符串常量资源应该使用ResourceBundle方式提供。
附录1代码注释示范及效果
Eclipse代码注释模板文件（aspire_codetemplates4Eclipse.xml）：
示范类文件（JavaDocClass）：
示范类文件产生的JavaDoc文件：
附录2代码的21种“坏味道”
应该在编程中尽量避免这21种“坏味道”。
1.DuplicatedCode
代码重复几乎是最常见的异味了。
他也是Refactoring的主要目标之一。
代码重复往
往来自于copy-and-paste的编程风格。
2.Longmethod
它是传统结构化的“遗毒“。
一个方法应当具有自我独立的意图，不要把几个意图
放在一起。
3．LargeClass
大类就是你把太多的责任交给了一个类。
这里的规则是OneClassOneResponsibility。
4．DivergentChange
一个类里面的内容变化率不同。
某些状态一个小时变一次，某些则几个月一年才变一次；某些状态因为这方面的原因发生变化，而另一些则因为其他方面的原因变一次。
面向对象的抽象就是把相对不变的和相对变化相隔离。
把问题变化的一方面和另一方面相隔离。
这使得这些相对不变的可以重用。
问题变化的每个方面都可以单独重用
升级会员 