Java编码书写规范完整版Word文件下载.docx
《Java编码书写规范完整版Word文件下载.docx》由会员分享,可在线阅读,更多相关《Java编码书写规范完整版Word文件下载.docx(18页珍藏版)》请在冰豆网上搜索。
4.9.小括号()15
4.10.运算符15
4.11.参数间隔15
4.12.JSP文件命名16
4.13.Servlet类命名(待定)16
5.编码指南16
5.1.对实例以及类变量的访问控制16
5.2.引用类变量和类方法16
5.3.常量17
5.4.变量赋值17
5.5.其它惯例18
5.5.1.圆括号18
5.5.2.返回值18
5.5.3.条件运算符"
?
"
前的表达式19
5.5.4.特殊注释19
5.5.5.异常使用原则19
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
类的注释
*<
p>
Title:
文件名称<
/p>
Description:
类内容的简介<
<
b>
更新记录:
/b>
*格式:
[更新日期][修改的版本][操作人]内容<
br>
*[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之间用逗号隔开,结尾不要分号--%>
java.util.*"
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();
//用这种方式
||(condition3&
||!
doSomethingAboutIt();
//或者这种方式
condition2)||(condition3&
||!
这里有三种可行的方法用于处理三元运算表达式:
alpha=(aLongBooleanExpression)?
beta:
gamma;
beta
:
alpha=(aLongBooleanExpression)
?
:
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<
size;
i++){
…
5.4.变量赋值
在一个语句中不允许给多个变量赋相同的值。
它很难读懂。
fooBar.fChar=barFoo.lchar='
c'
;
//避免!
不要将赋值运算