Java编码书写规范.docx
《Java编码书写规范.docx》由会员分享，可在线阅读，更多相关《Java编码书写规范.docx（19页珍藏版）》请在冰豆网上搜索。
Java编码书写规范
济南广域软件有限公司
Java编码书写规范（v1.1）
济南广域软件有限公司
2009年3月
1.命名约定
除了以下几个特例之外，命名时必须始终采用完整的英文描述符。
此外，一般应采用小写字母，但类名、接口名以及任何非初始单词的第一个字母要大写。
1.1.一般概念
☞尽量使用完整的英文描述符
☞采用适用于相关领域的术语
☞采用大小写混合使名字可读
☞尽量少用缩写，但如果用了，要明智地使用，且在整个工程中统一
☞避免使用长的名字（尽量小于25个字母）
☞避免使用类似的名字，或者仅仅是大小写不同的名字
☞避免使用下划线（除静态常量等）
1.2.示范
包（Package）采用完整的英文描述符，应该都是由小写字母组成，格式为com.dcosft.*。
如：
com.dcsoft.ework.workflow
mons
com.dcsoft.utility
类（Class）采用完整的英文描述符，所有单词的第一个字母大写，在上下文语境允许的情况下，可以使用缩略词，但必须保证整个开发小组的一致性，比如：
number可缩写为num。
如：
Customer
SavingsAccount
接口（Interface）采用完整的英文描述符说明接口封装，所有单词的第一个字母大写。
在接口名称的最前面使用大写的“I”表明这是一个接口。
习惯上，名字后面加上后缀able，ible或者er，但这不是必需的。
如：
IContactable
IPrompter
组件/部件（Component）使用完整的英文描述来说明组件的用途，前端加上组件类型。
如：
btnOK
lstCustomer
menuFile
异常（Exception）采用异常类型的各单词首字母表示异常。
如：
Excpetione
IOExceptionioe
字段/属性字段采用完整的英文描述，第一个字母小写，任何中间单词的首字母大写。
firstName
lastName
实参/参数同字段/属性的命名规则
publicvoidsetFirstName（StringfirstName）{
this.firstName=firstName;
}
局部变量同字段/属性的命名规则
获取成员函数被访问字段名的前面加上前缀get。
getFirstName（）
getLastName（）
布尔型的获取成员函数所有的布尔型获取函数必须用单词is做前缀。
isPersistent（）
isString（）
设置成员函数被访问字段名的前面加上前缀set。
setFirstName（）
setLastName（）
setWarpSpeed（）
普通成员函数采用完整的英文描述说明成员函数功能，第一个单词尽可能采用一个动词，第一个字母小写。
openFile（）
addAccount（）
静态常量字段（staticfinal）全部采用大写字母，单词之间用下划线分隔。
MIN_BALANCE,
DEFAULT_DATE
循环计数器通常采用字母i，j，k，m，n或者counter都可以接受。
i,j,k
m,n,counter
数组应该总是用下面的方式来命名：
objectType[]variant，不得使用objectTypevariant[]方式。
int[]arrInt;
String[]args;
对象实例同组件/部件
byte[]arrBuffer;
StringBuffersbContent;
2.注释约定
2.1.一般概念
☞注释应该增加代码的清晰度
☞保持注释的简洁
☞在写代码之前写注释
☞注释出为什么做了一些事，而不仅仅是做了什么
2.2.示范
文档注释在紧靠接口、类、成员函数和字段声明的前面注释它们。
/**客户：
客户是我们将服务和产品卖给的人或机构。
*/
Stringcustomer;
C语言风格注释采用C语言风格的注释去掉不再使用但你仍想保留的代码。
仍想保留是因为用户万一会改变想法，或者在调试过程中想让它暂时失效。
/*这部分代码因为已被它之前的代码取代，由B.Gustafsson,
*于1999年6月4日注释掉。
如果两年之后还未使用，将
*其删除。
...
*（源代码）
*/
单行注释在成员函数内采用单行注释，来说明业务逻辑、代码段和暂时变量的声明。
注释符"//"后必须紧跟一个空格，然后才是注释信息。
//遵照Sarek的规定，给所有
//超过$1000的发货单
//打5%的折扣。
让利活
//动于1995年2月开始.
if（condition）{/*处理条件*/
...
}
即约定主要的说明性注释使用文档注释；C风格注释只用来标注过期不用的代码；单行注释用来标注一些简单却容易混淆的逻辑，比较长的单独作为一行，较简洁的可以放在代码行尾。
2.3.注释范围
类：
类的目的、即类所完成的功能，注释出采用的变量。
接口：
注释描述设置接口的目的、它应如何被使用。
成员函数：
对于设置与获取成员函数，在成员变量已有说明的情况下，可以不加注释；普通成员函数注释要求说明完成什么功能，参数含义及返回什么；
普通成员函数内部控制结构：
注释代码做了些什么以及为什么这样做，处理顺序等。
实参/参数：
注释参数含义、及其它任何约束或前提条件
字段/属性：
注释字段的描述
局部变量：
无特别意义的情况下不加注释
3.文件样式约定
3.1.Java（*.java）
所有的Java（*.java）文件都必须遵守如下的样式规则：
3.1.1.版权信息
版权信息必须在java文件的开头，比如：
/**
*Copyright2009WatSoftCo.Ltd.
*Allrightreserved.
*Author
*Date2009-02-27
*/
作者名称要用中文。
其他不需要出现在javadoc的信息也可以包含在这里。
3.1.2.Package/Imports
package行要在import行之前，import中标准的包名要在本地的包名之前，而且按照字母顺序排列。
如果import行中包含了同一个包中的不同子目录，则应该用*来处理。
package.stats;
importjava.io.*;
importjava.util.Observable;
importhotlava.util.Application;
这里java.io.*是用来代替InputStreamandOutputStream的。
3.1.3.Class
类的注释
/**
*
Title:
文件名称
*
Description:
类内容的简介
*
更新记录：
*格式:
[更新日期][修改的版本][操作人]内容
*[2005-06-28][1.0][张三]完善create方法。
*
*
Copyright:
Copyright（c）2009
*
Company:
WatSoftCo.Ltd.
*@version:
1.1
*/
类定义：
包含了在不同行的extends和implements
publicclassCounterSet
extendsObservable
implementsCloneable{
……
}
3.1.4.ClassFields
类的成员变量：
/**
*Packetcounters
*/
protectedint[]packets;
public的成员变量必须生成文档（JavaDoc）。
proceted、private和package定义的成员变量如果名字含义明确的话，可以没有注释。
类变量的存取：
如类的成员变量已经有注释，类变量的存取方法可以没有注释。
publicint[]getPackets（）{
returnthis.packets;
}
publicvoidsetPackets（int[]packets）{
this.packets=packets;
}
……
3.1.5.构造函数
构造函数：
应该用递增的方式写（比如：
参数多的写在后面）。
publicCounterSet（）{
this.size=100;
}
publicCounterSet（intsize）{
this.size=size;
}
3.1.6.克隆方法
如果这个类是可以被克隆的，那么下一步就是clone方法：
publicObjectclone（）{
try{
……
}catch（CloneNotSupportedExceptione）{
……
}
}
3.1.7.类方法（类的普通成员函数）
类的方法：
/**
*Setthepacketcounters
*paramr1-……
*paramr2-……
*……
*/
protectedfinalvoidsetArray（int[]r1,int[]r2,int[]r3,int[]r4）
throwsIllegalArgumentException{
//Ensurethearraysareofequalsize……
}
3.1.8.toString方法
一般情况下，每一个类都应该定义toString方法：
publicStringtoString（）{
……
}
3.1.9.main方法
普通类，考虑置入一个main（）方法，其中包含用于测试那个类的代码，如果包含了main（）方法,那么它应该写在类的底部。
3.2.JavaServerPage（*.jsp）
所有的Jsp（*.jsp）文件都必须遵守如下的样式规则：
3.2.1.版本信息
文件开头应有一个文件的版本注释，格式为
<%--Copyright：
Copyright2009--%>
<%--Company：
WatSoftCo.Ltd--%>
<%------------------------------------------------------------
功能简介：
对这一个实现的功能作一个简介。
传入参数：
列出该页接收的所有参数
传入参数的说明，以及没有接收到参数的处理方式
如果有session，列出所有的session，然后说明session，
以及session的影响
----------------------------------------------------------------%>
<%--Version：
版本号--%>
<%--[更新日期][修改的版本][操作人]内容--%>
<%--[2005-06-28][1.0][张三]完善create方法。
--%>
……………
3.2.2.tag
关键tag的书写顺序为
<%@pageimport=""%>
<%@includefile=""%>
注意事项
☞使用国标扩展字符集（GBK）作为content的charset
<%@pageContentType="text/html;charset=GBK"%>
☞contentType在被包含的文件一定不能写，而其他文件一定要写
☞建议用以下两种格式：
<%@pageimport="java.util.*,java.sql.*"%>
<%--多个import之间用逗号隔开，结尾不要分号--%>
<%@pageimport="java.util.*"%>
<%@pageimport="java.sql.*"%>
<%--所有的import均分开写--%>
☞tag一律用小写，属性的值用双引号引起来。
☞出错信息定向到公用的出错页面
☞JSP页面与java编码要完全分离（待补充）。
3.2.3.值输出
输出值时使用<%=value%>。
3.2.4.嵌入代码段
使用单独行“<%”开头，单独行“%>”结尾，注释参见2，代码块缩进参见4.2。
<%
for（inti=0;i<10;i++）{
out.println（i）;
}
%>
4.其它代码书写风格约定
4.1.文档自动生成
必须用javadoc来为类生成文档。
不仅因为它是标准，这也是被各种java编译器都认可的方法。
使用@author标记是不被推荐的，因为代码不应该是被个人拥有的。
4.2.缩进
缩进是必须的，并且在同一系统所有编码的缩进风格必须是统一的。
4.3.页宽
页宽应该设置为80字符，源代码不能超过此宽度。
在任何情况下，超长的语句应该在一个逗号或者一个操作符后折行。
一条语句折行后，应该比原来的语句再缩进3个字符。
当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：
✧在一个逗号后面断开
✧在一个操作符前面断开
✧宁可选择较高级别（higher-level）的断开，而非较低级别（lower-level）的断开
✧新的一行应该与上一行同一级别表达式的开头处对齐
✧如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。
以下是两个断开算术表达式的例子。
前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。
longName1=longName2*（longName3+longName4-longName5）
+4*longname6;//参考
longName1=longName2*（longName3+longName4
-longName5）+4*longname6;//避免
以下是两个缩进方法声明的例子。
前者是常规情形。
后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进8个空格
//常规缩进
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
//制表符缩进
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
if语句的换行通常使用8个空格的规则，因为常规缩进（4个空格）会使语句体看起来比较费劲。
比如：
//不要用这种方式
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
//用这种方式
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
//或者这种方式
if（（condition1&&condition2）||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
这里有三种可行的方法用于处理三元运算表达式：
alpha=（aLongBooleanExpression）?
beta:
gamma;
alpha=（aLongBooleanExpression）?
beta
:
gamma;
alpha=（aLongBooleanExpression）
?
beta
:
gamma;
4.4.变量声明
必须一行一个声明，因为这样以利于写注释。
亦即，
intlevel;//标识层级别
intsize;//表大小
要优于，
intlevel,size;
4.5.变量初始化
尽量在声明局部变量的同时初始化。
唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。
4.6.局部变量声明
只在代码块的开始处声明变量。
（一个块是指任何被包含在大括号"{"和"}"中间的代码。
）不要在首次用到该变量时才声明之。
4.7.空行
空行将逻辑相关的代码段分隔开，以提高可读性。
下列情况应该总是使用两个空行：
✧一个源文件的两个片段（section）之间
✧类声明和接口声明之间
✧下列情况应该总是使用一个空行：
✧两个方法之间
✧方法内的局部变量和方法的第一条语句之间
✧一个方法内的两个逻辑段之间，用以提高可读性
4.8.大括号{}
{}中的语句应该单独作为一行。
例如：
if（i>0）{
i++;
}
4.9.小括号（）
左括号和后一个字符之间不应该出现空格；同样，右括号和前一个字符之间也不应该出现空格。
例如：
CallProc（AParameter）;//不符合规范
CallProc（AParameter）;//符合规范
不要在语句中使用无意义的括号，括号只应该为达到某种目的而出现在源代码中。
4.10.运算符
每个运算符与两边的字符之间都应该有一个空格。
intnum=100;//符合规范
num+=1;//符合规范
num=num-1;//不符合规范，应该是num=num-1;
4.11.参数间隔
多个参数之间的“，”应紧跟前面的参数，与后面的参数之间有一个空格。
publicintmax（inta,intb,intc）{//符合规范
returnMath.max（Math.max（a,b）,c）;//不符合规范，a后面应该由空格，
//b和c的前面也应该由空格
}
4.12.JSP文件命名
采用完整的英文描述说明JSP所完成的功能，尽可能包括一个动词，第一个字母小写，如：
viewMessage.jsp、editUser.jsp或者forumChooser.jsp等。
4.13.Servlet类命名（待定）
一般对应于所服务的对象加后缀Service来命名，如：
UserService，TradeService等。
5.编码指南
5.1.对实例以及类变量的访问控制
若没有足够理由，不要把实例或类变量声明为公有。
所有类成员变量要通过方法访问。
通常，实例变量无需显式的设置（set）和获取（gotten），通常这作为方法调用的边缘效应（sideeffect）而产生。
一个具有公有实例变量的恰当例子，是类仅作为数据结构，没有行为。
亦即，若你要使用一个结构（struct）而非一个类（如果java支持结构的话），那么把类的实例变量声明为公有是合适的。
5.2.引用类变量和类方法
避免用一个对象访问一个类的静态变量和方法。
应该用类名替代。
例如：
classMethod（）;//正确
AClass.classMethod（）;//正确
anObject.classMethod（）;//避免!
5.3.常量
Java中的常量值要用字符串表示,它区分为不同的类型,如整型常量123,实型量1.23,字符常量‘a’,布尔常量true、false以及字符串常量"Thisisaconstantstring."。
例如：
finaldoublePI=3.14159;
位于for循环中作为计数器值的数字常量，除了-1,0和1之外，不应被直接写入代码。
例如：
for（inti=0;i…
}
5.4.变量赋值
在一个语句中不允许给多个变量赋相同的值。
它很难读懂。
例如：
fooBar.fChar=barFoo.lchar='c';//避免!
不要将赋值运算符用在容易与相等关系运算符混淆的地方。
例如：
if（c++=d++）{//避免!
Java不允许
...
}
应该写成
if（（c++=d++）!
=0）{
...
}
不要使用内嵌（embedded）赋值运算符试图提高运行时的效率，这是编译器的工作。
例如：
d=（a=b+c）+r;//避免!
应该写成
a=b+c;
d=a+r;
5.5.其它惯例
5.5.1.圆括号
一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。
即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。
你不能假设别的程序员和你一样清楚运算符的优先级。
if（a==b&&c==d）//避免!
if（（a==b）&&（c==d））//正确
5.5.2.返回值
设法让你的程序结构符合目的。
例如：
if（booleanExpression）{
returntrue;
}else{
returnfalse;
}
应该代之以如下方法：
returnbooleanExpression;
类似地：
if（condition）{
returnx;
}
returny;
应该写做：
return（condition?
x:
y）;
5.5.3.条件运算符"?
"前的表达式
如果一个包含二元运算符的表达式出现在三元运算符"?
:
"的"?
"之前，那么应该给表达式添上一对圆括号。
例如：
（x>=0）?
x:
-x;
5.5.4.特殊注释
在注释中使用XXX来标识某些未实现（bogus）的但可以工作（works）的内容。
用FIXME来标识某些假的和错误的内容。
5.5.5.异常使用原则
✧异常在java编码过程中，在使用过程中应该注意遵守以下原则：
✧首先，不要丢弃异常，即catch异常后什么也不做。
如果你认为不能很好的处理该异常，就让它继续传播，让别的地方处理去；或者，你可以把一个
升级会员 