JAVA编程规范尹著.docx
《JAVA编程规范尹著.docx》由会员分享,可在线阅读,更多相关《JAVA编程规范尹著.docx(19页珍藏版)》请在冰豆网上搜索。
JAVA编程规范尹著
1Java编程规范
1.1排版
1.1.1规则
规则1程序块要采用缩进风格编写,缩进的空格数为4个,不允许使用TAB缩进。
+)
说明:
缩进使程序更易阅读,使用空格缩进可以适应不同操作系统与不同开发工具。
规则2分界符(如大括号‘{’和‘}’)应各独占一行,同时与引用它们的语句左对齐。
在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序或者static、,synchronized等语句块中都要采用如上的缩进方式。
+)
示例:
if(a>b){
doStart();
}
规则3较长的语句、表达式或参数(>80字符)要分成多行书写,长表达式要在低优先级操作符处划分新行,操作符放在新行之首,划分出的新行要进行适当的缩进,使排版整齐,语句可读。
+)
示例:
if()){
("Sessiondestroyed,call-id"
+().getCallId());
}
规则4不允许把多个短语句写在一行中,即一行只写一条语句+)
说明:
阅读代码更加清晰
示例:
如下例子不符合规范。
Objecto=newObject();Objectb=null;
规则5if,for,do,while,case,switch,default等语句自占一行,且if,for,do,while,switch等语句的执行语句无论多少都要加括号{},case的执行语句中如果定义变量必须加括号{}。
+)
说明:
阅读代码更加清晰,减少错误产生
示例:
if(a>b){
doStart();
}
casex:
{
inti=9;
}
规则6相对独立的程序块之间、变量说明之后必须加空行。
+)
说明:
阅读代码更加清晰
示例:
if(a>b){
doStart();
}
规则7,后不应加空格。
+)
说明:
阅读代码更加清晰
示例:
if(a==b){
();
}
a*=2;
1.1.2建议
建议1类属性和类方法不要交叉放置,不同存取范围的属性或者方法也尽量不要交叉放置。
+)
格式:
类定义
{
类的公有属性定义
类的保护属性定义
类的私有属性定义
类的公有方法定义
类的保护方法定义
类的私有方法定义
}
建议2修饰词按照指定顺序书写:
[访问权限][static][final]。
+)
示例:
publicstaticfinalStringstr=“abc”;
1.2注释
1.2.1规则
规则8源程序注释量必须在30%以上。
+)
说明:
由于每个文件的代码注释不一定都可以达到30%,建议以一个系统内部模块作为单位进行检查
规则9包的注释:
写入一个名为的HTML格式的说明文件放入包所在路径。
包的注释内容:
简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。
+)
说明:
方便JavaDoc收集,方便对包的了解
示例:
com/hc/iin/websmap/comm/
一句话简述。
详细描述。
产品模块名称和版本
公司版权信息
示例:
为WEBSMAP提供通信类,上层业务使用本包的通信类与SMP-B进行通信。
详细描述。
。
。
。
。
。
。
。
IINV100R001WEBSMAP
(C)版权所有2000-2001华为技术有限公司
规则10类和接口的注释放在class或者interface关键字之前,import关键字之后。
注释主要是一句话功能简述与功能详细描述。
类注释使用“/***/”注释方式+)
说明:
方便JavaDoc收集,没有import可放在package之后。
注释可根据需要列出:
作者、内容、功能、与其它类的关系等。
功能详细描述部分说明该类或者接口的功能、作用、使用方法和注意事项,每次修改后增加作者和更新版本号和日期,@since表示从那个版本开始就有这个类或者接口,@deprecated表示不建议使用该类或者接口。
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@author[作者](必须)
*@see[相关类/方法](可选)
*@since[产品/模块版本](必须)
*@deprecated(可选)
*/
示例:
package.*;
/**
*LogManager类集中控制对日志读写的操作。
*全部为静态变量和静态方法,对外提供统一接口。
分配对应日志类型的读写器,
*读取或写入符合条件的日志纪录。
*@author张三,李四,王五
*@seeLogIteraotor
*@seeBasicLog
*@since
*/
publicclassLogManager
规则11类属性(成员变量)、公有和保护方法注释:
写在类属性、公有和保护方法上面,注释方式为“/***/”.+)
示例:
/**
*注释内容
*/
privateStringlogType;
/**
*注释内容
*/
publicvoidwrite()
规则12公有和保护方法注释内容:
列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、异常等。
+)
格式:
/**
*〈一句话功能简述〉
*〈功能详细描述〉
*@param[参数1][参数1说明]
*@param[参数2][参数2说明]
*@return[返回类型说明]
*@exception/throws[异常类型][异常说明][可选]
*@see[类、类#方法、类#成员]
*@since[起始版本]
*@deprecated
*/
说明:
@since表示从那个版本开始就有这个方法,如果是最初版本就存在的方法无需说明;@exception或throws列出可能仍出的异常;@deprecated表示不建议使用该方法。
示例:
/**
*根据日志类型和时间读取日志。
*分配对应日志类型的LogReader,指定类型、查询时间段、条件和反复器缓冲数,
*读取日志记录。
查询条件为null或0的表示没有限制,反复器缓冲数为0读不到日志。
*查询时间为左包含原则,即[startTime,endTime)。
*@paramlogTypeName日志类型名(在配置文件中定义的)
*@paramstartTime查询日志的开始时间
*@paramendTime查询日志的结束时间
*@paramlogLevel查询日志的级别
*@paramuserName查询该用户的日志
*@parambufferNum日志反复器缓冲记录数
*@return结果集,日志反复器
*@since
*/
publicstaticLogIteratorread(StringlogType,DatestartTime,DateendTime,intlogLevel,StringuserName,intbufferNum)
规则13注释应与其描述的代码相近,对代码的注释应放在其上方,并与其上面的代码用空行隔开,注释与所描述内容进行同样的缩排。
+)
说明:
可使程序排版整齐,并方便注释的阅读与理解。
示例:
/*
*注释
*/
publicvoidexample2()
{
如果能被4整除,是闰年;
如果能被100整除,不是闰年;
如果能被400整除,是闰年。
1.3命名
1.3.1规则
规则14类名和接口使用类意义完整的英文描述,每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。
+)
示例:
OrderInformation,CustomerList,LogManager,LogConfig,SmpTransaction
规则15方法名使用类意义完整的英文描述:
第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
+)
示例:
privatevoidcalculateRate();
publicvoidaddNewOrder();
规则16方法中,存取属性的方法采用setter和getter方法,动作方法采用动词和动宾结构。
+)
格式:
get+非布尔属性名()
is+布尔属性名()
set+属性名()
动词()
动词+宾语()
示例:
publicStringgetType();
publicbooleanisFinished();
publicvoidsetVisible(boolean);
publicvoidshow();
publicvoidaddKeyListener(Listener);
规则17属性名使用意义完整的英文描述,第一个单词的字母使用小写,剩余单词首字母大写其余字母小写的大小写混合法。
属性名不能与方法名相同。
+)
示例:
privatecustomerName;
privateorderNumber;
privatesmpSession;
规则18常量名使用全大写的英文描述,英文单词之间用下划线分隔开,并且使用staticfinal修饰。
+)
示例:
publicstaticfinalintMAX_VALUE=1000;
publicstaticfinalStringDEFAULT_START_DATE="2001-12-08";
1.3.2建议
建议3包名采用域后缀倒置的加上自定义的包名,采用小写字母,都应该以开头(不包括一些特殊原因)。
在部门内部应该规划好包名的范围,防止产生冲突。
部门内部产品使用部门的名称加上模块名称。
产品线的产品使用产品的名称加上模块的名称。
+)
说明:
除特殊原因包结构都必须以开头,如果因为OEM合作等关系,可以不做要求。
格式:
.产品名.模块名称
示例:
建议4融合WEBSMAP包名通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
+)
说明:
清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。
建议5常用组件类的命名以组件名加上组件类型名结尾。
+)
示例:
Application类型的,命名以App结尾——MainApp
Frame类型的,命名以Frame结尾——TopoFrame
Panel类型的,建议命名以Panel结尾——CreateCircuitPanel
Bean类型的,建议命名以Bean结尾——DataAccessBean
建议6如果函数名超过15个字母,可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。
+)
示例:
getCustomerInformation()改为getCustomerInfo()
建议7准确地确定成员函数的存取控制符号:
只是该类内部调用的函数使用private属性,继承类可以使用的使用protected属性,同包类可以调用的使用默认属性(不加属性控制符号),对外公开的函数使用public属性+)
示例:
protectedvoidgetUserName(){
。
。
。
。
。
。
}
privatevoidcalculateRate(){
。
。
。
。
。
。
}
建议8含有集合意义的属性命名,尽量包含其复数的意义。
+)
示例:
customers,orderItems
1.4编码
1.4.1规则
规则19数据库操作、IO操作等需要使用结束close()的对象必须在try-catch-finally的finally中close(),如果有多个IO对象需要close(),需要分别对每个对象的close()方法进行try-catch,防止一个IO对象关闭失败其他IO对象都未关闭。
+)
示例:
try
{
....
}
catch(IOExceptionioe)
{
...
}
finally
{
try
{
();
}
catch(IOExceptionioe)
{
...
}
try
{
();
}
catch(IOExceptionioe)
{
...
}
}
规则20系统非正常运行产生的异常捕获后,如果不对该异常进行处理,则应该记录日志。
+)
说明:
此规则指通常的系统非正常运行产生的异常,不包括一些基于异常的设计。
若有特殊原因必须用注释加以说明。
示例:
try
{
....
}
catch(IOExceptionioe)
{
(ioe);
}
规则21自己抛出的异常必须要填写详细的描述信息。
+)
说明:
便于问题定位。
示例:
thrownewIOException("Writingdataerror!
Data:
"+());
规则22运行时异常使用RuntimeException的子类来表示,不用在可能抛出异常的方法声明上加throws子句。
非运行期异常是从Exception继承而来的,必须在方法声明上加throws子句。
+)
说明:
非运行期异常是由外界运行环境决定异常抛出条件的异常,例如文件操作,可能受权限、磁盘空间大小的影响而失败,这种异常是程序本身无法避免的,需要调用者明确考虑该异常出现时该如何处理方法,因此非运行期异常必须有throws子句标出,不标出或者调用者不捕获该类型异常都会导致编译失败,从而防止程序员本身疏忽。
运行期异常是程序在运行过程中本身考虑不周导致的异常,例如传入错误的参数等。
抛出运行期异常的目的是防止异常扩散,导致定位困难。
因此在做异常体系设计时要根据错误的性质合理选择自定义异常的继承关系。
还有一种异常是Error继承而来的,这种异常由虚拟机自己维护,表示发生了致命错误,程序无法继续运行例如内存不足。
我们自己的程序不应该捕获这种异常,并且也不应该创建该种类型的异常。
规则23在程序中使用异常处理还是使用错误返回码处理,根据是否有利于程序结构来确定,并且异常和错误码不应该混合使用,推荐使用异常。
+)
说明:
一个系统或者模块应该统一规划异常类型和返回码的含义。
但是不能用异常来做一般流程处理的方式,不要过多地使用异常,异常的处理效率比条件分支低,而且异常的跳转流程难以预测。
注意:
Java程序内部的错误码可以使用枚举来表示。
规则24注意运算符的优先级,并用括号明确表达式的操作顺序,避免使用默认优先级。
+)
说明:
防止阅读程序时产生误解,防止因默认的优先级与设计思想不符而导致程序出错。
示例:
下列语句中的表达式
word=(high<<8)|low
(1)
if((a|b)&&(a&c))
(2)
if((a|b)<(c&d))(3)
如果书写为
high<<8|low
a|b&&a&c
a|b(1)
(2)虽然不会出错,但语句不易理解;(3)造成了判断条件出错。
规则25避免使用不易理解的数字,用有意义的标识来替代。
涉及物理状态或者含有物理意义的常量,不应直接使用数字,必须用有意义的静态变量或者枚举来代替。
使用异常来表示方法执行错误,而不是使用C++的错误返回码方式。
+)
示例:
如下的程序可读性差。
if(state==0)
{
state=1;
.....
thrownewRuntimeException(“。
。
。
”);
}
规则26数组声明的时候使用int[]index,而不要使用intindex[]。
+)
说明:
使用intindex[]格式使程序的可读性较差,int[]index表示声明了一个int数组(int[])叫做index
示例:
如下程序可读性差:
publicintgetIndex()[]
{
....
}
如下程序可读性好:
publicint[]getIndex()
{
....
}
规则27不要使用与进行控制台打印,应该使用工具类(如:
日志工具)进行统一记录或者打印。
+)
说明:
代码发布的时候可以统一关闭控制台打印,代码调试的时候又可以打开控制台打印,方便调试。
规则28一个文件不要定义两个类(并非指内部类)。
+)
说明:
方便程序的阅读与代码的维护
规则29所有的数据类必须覆写toString()、hashCode()、equals()方法,toString()方法返回该类有意义的内容。
+)
说明:
方便数据类的比较,父类如果实现了比较合理的toString(),子类可以继承不必再重写。
hashCode与equals可以使用eclipse自动生成。
示例:
publicTopoNode
{
privateStringnodeName;
publicStringtoString()
{
return"NodeName:
"+nodeName;
}
}
规则30判断语句不要使用”*==true”来判断为真
说明:
方便阅读,减少没有必要的计算
以下错误:
if(ok==true)
{
……
}
以下正确:
if(ok)
{
……
}
规则31不要写没有必要的向上强制转型。
+)
说明:
没必要写的向上强制转型会浪费性能,增加代码阅读难度
示例:
以下错误:
FileInputStreamfis=newFileInputStream(f);
InputStreamis=(InputStream)fis;
1.4.2建议
建议9记录异常不要保存(),而要记录(),一般可通过日志工具记录完整的异常堆栈信息。
+)
说明:
NullPointException抛出时常常描述为空,这样往往看不出是出了什么错。
示例:
try
{
...
}
catch(FileNotFoundExceptione)
{
(e);
}
建议10一个方法不应抛出太多类型的异常。
+)
说明:
如果程序中需要分类处理,则将异常根据分类组织成继承关系。
如果确实有很多异常类型首先考虑用异常描述来区别,throws/exception子句标明的异常最好不要超过三个。
建议11异常捕获尽量不要直接catch(Exceptionex),应该把异常细分处理。
+)
说明:
可以设计更合理异常处理分支
建议12如果多段代码重复做同一件事情,那么在方法的划分上可能存在问题。
+)
说明:
若此段代码各语句之间有实质性关联并且是完成同一件功能的,那么可考虑把此段代码构造成一个新的方法。
建议13集合中的数据如果不使用了应该及时释放,尤其是可重复使用的集合。
+)
说明:
由于集合保存了对象的引用,虚拟机的垃圾收集器就不会回收。
建议14源程序中关系较为紧密的代码应尽可能相邻。
+)
说明:
便于程序阅读和查找。
示例:
矩形的长与宽关系较密切,放在一起。
=10;
=5;
建议15不要使用难懂的技巧性很高的语句,除非很有必要时。
+)
说明:
高技巧语句不等于高效率的程序,实际上程序的效率关键在于设计与算法。
建议16明确方法功能,精确(而不是近似)地实现方法设计。
一个函数仅完成一件功能,即使简单功能也编写方法实现。
+)
说明:
虽然为仅用一两行就可完成的功能去编方法好象没有必要,但用方法可使功能明确化,增加程序可读性,亦可方便维护、测试。
建议17应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责,缺省是由方法调用者负责。
+)
说明:
对于模块间接口方法的参数的合法性检查这一问题,往往有两个极端现象,即:
要么是调用者和被调用者对参数均不作合法性检查,结果就遗漏了合法性检查这一必要的处理过程,造成问题隐患;要么就是调用者和被调用者均对参数进行合法性检查,这种情况虽不会造成问题,但产生了冗余代码,降低了效率。
建议18尽量使用Java新循环写法。
+)
说明:
代码更加简洁
示例:
ArrayListlist=newArrayList();
...
for(Stringstr:
list)
{
建议19使用Java枚举来替代以前用数字与字符串的同等目的的操作。
+)
说明:
Java以前没有枚举,大家都用数字或者字符串做枚举同样功能的事情
示例:
publicenumEnumDemo
{
ERROR,INFO,DEBUG
}
Inotherfunction:
EnumDemot=;
if(t==
{
。
。
。
。
。
。
}
建议20interface中定义的常量不要写public、static、final的修饰词,方法不要写public修饰词。
+)
说明:
更加简洁
示例:
publicinterfaceInterfaceT
{
StringTT="abcl";
voiddoStart();
}
建议21新起一个线程,都要使用(“…”)设置线程名。
说明:
性能测试时可对线程状态进行监控,异常时也可以知道异常发生在哪个线程中
1.5性能与可靠性
1.5.1规则
规则32对Debug,Info级别日志输出前必须对当前的调试等级先进行判断。
+)
说明:
日志一般都会有不少字符串的处理,如果不是Debug级别就没有必要进行处理
示例:
if())
{
(“request:
”+());
}
规则33数组复制使用(*)。
+)
说明:
更好的性能
规则34不要使用循环将集合转为数组,可以使用集合的toArray()方法。
+)
说明:
更好的性能,代码更加简洁
示例:
ArrayListlist=newArrayList();
....
String[]array=newString[()];
(array);
规则35大量字符串的相加等于处理应该使用StringBuffer。
+)
说明:
大量的String相加等于处理性能消耗较多。
“大量”一般指5次“+=”以上或者在循环中进行字符串+=操作。
示例:
不推荐:
Stringstr=“”;
str+=”a”;
str+=”b”;
推荐:
StringBuffersb=newStringBuffer();
(“aa”);
(“bb”);
(“cc”);
规则36对类中日志工具对象logger应声明为s