java程序编写规范文档格式.docx
《java程序编写规范文档格式.docx》由会员分享,可在线阅读,更多相关《java程序编写规范文档格式.docx(17页珍藏版)》请在冰豆网上搜索。
版权信息
版权信息必须在java文件的开头,比如:
/**
*Copyright?
2000ShanghaiXXXCo.Ltd.
*Allrightreserved.
*/
其他不需要出现在javadoc的信息也可以包含在这里。
Package/Imports
package行要在import行之前,import中标准的包名要在本地的包名之前,而且按照字母顺序排列。
如果import行中包含了同一个包中的不同子目录,则应该用*来处理。
package.stats;
importjava.io.*;
importjava.util.Observable;
importhotlava.util.Application;
这里java.io.*使用来代替InputStreamandOutputStream的。
Class
接下来的是类的注释,一般是用来解释类的。
*Aclassrepresentingasetofpacketandbytecounters
*Itisobservabletoallowittobewatched,butonly
*reportschangeswhenthecurrentsetiscomplete
接下来是类定义,包含了在不同的行的extends和implements
publicclassCounterSet
extendsObservable
implementsCloneable
ClassFields
接下来是类的成员变量:
*Packetcounters
protectedint[]packets;
public的成员变量必须生成文档(JavaDoc)。
proceted、private和package定义的成员变量如果名字含义明确的话,可以没有注释。
存取方法
接下来是类变量的存取的方法。
它只是简单的用来将类的变量赋值获取值的话,可以简单的写在一行上。
*Getthecounters
*@returnanarraycontainingthestatisticaldata.Thisarrayhasbeen
*freshlyallocatedandcanbemodifiedbythecaller.
publicint[]getPackets(){returncopyArray(packets,offset);
}
publicint[]getBytes(){returncopyArray(bytes,offset);
publicint[]getPackets(){returnpackets;
publicvoidsetPackets(int[]packets){this.packets=packets;
其它的方法不要写在一行上
构造函数
接下来是构造函数,它应该用递增的方式写(比如:
参数多的写在后面)。
访问类型("
public"
"
private"
等.)和任何"
static"
final"
或"
synchronized"
应该在一行中,并且方法和参数另写一行,这样可以使方法和参数更易读。
public
CounterSet(intsize){
this.size=size;
克隆方法
顶
6
2007-1-1218:
44
回复
220.207.106.*
2楼
如果这个类是可以被克隆的,那么下一步就是clone方法:
Objectclone(){
try{
CounterSetobj=(CounterSet)super.clone();
obj.packets=(int[])packets.clone();
obj.size=size;
returnobj;
}catch(CloneNotSupportedExceptione){
thrownewInternalError("
UnexpectedCloneNotSUpportedException:
"
+e.getMessage());
类方法
下面开始写类的方法:
*Setthepacketcounters
*(suchaswhenrestoringfromadatabase)
protectedfinal
voidsetArray(int[]r1,int[]r2,int[]r3,int[]r4)
throwsIllegalArgumentException
{
//
//Ensurethearraysareofequalsize
if(r1.length!
=r2.length||r1.length!
=r3.length||r1.length!
=r4.length)
thrownewIllegalArgumentException("
Arraysmustbeofthesamesize"
);
System.arraycopy(r1,0,r3,0,r1.length);
System.arraycopy(r2,0,r4,0,r1.length);
toString方法
无论如何,每一个类都应该定义toString方法:
StringtoString(){
Stringretval="
CounterSet:
;
for(inti=0;
i<
data.length();
i++){
retval+=data.bytes.toString();
retval+=data.packets.toString();
returnretval;
main方法
如果main(String[])方法已经定义了,那么它应该写在类的底部.
代码编写格式
代码样式
代码应该用unix的格式,而不是windows的(比如:
回车变成回车+换行)
文档化
必须用javadoc来为类生成文档。
不仅因为它是标准,这也是被各种java编译器都认可的方法。
使用@author标记是不被推荐的,因为代码不应该是被个人拥有的。
缩进
缩进应该是每行2个空格.不要在源文件中保存Tab字符.在使用不同的源代码管理工具时Tab字符将因为用户设置的不同而扩展为不同的宽度.
如果你使用UltrEdit作为你的Java源代码编辑器的话,你可以通过如下操作来禁止保存Tab字符,方法是通过UltrEdit中先设定Tab使用的长度室2个空格,然后用Format|TabstoSpaces菜单将Tab转换为空格。
页宽
页宽应该设置为80字符.源代码一般不会超过这个宽度,并导致无法完整显示,但这一设置也可以灵活调整.在任何情况下,超长的语句应该在一个逗号或者一个操作符后折行.一条语句折行后,应该比原来的语句再缩进2个字符.
{}对
{}中的语句应该单独作为一行.例如,下面的第1行是错误的,第2行是正确的:
if(i>
0){i++};
//错误,{和}在同一行
0){
i++
};
//正确,{单独作为一行
}语句永远单独作为一行.
如果}语句应该缩进到与其相对应的{那一行相对齐的位置。
括号
左括号和后一个字符之间不应该出现空格,同样,右括号和前一个字符之间也不应该出现空格.下面的例子说明括号和空格的错误及正确使用:
CallProc(AParameter);
//错误
CallProc(AParameter);
//正确
不要在语句中使用无意义的括号.括号只应该为达到某种目的而出现在源代码中。
下面的例子说明错误和正确的用法:
if((I)=42){//错误-括号毫无意义
if(I==42)or(J==42)then//正确-的确需要括号
程序编写规范
exit()
exit除了在main中可以被调用外,其他的地方不应该调用。
因为这样做不给任何代码代码机会来截获退出。
一个类似后台服务地程序不应该因为某一个库模块决定了要退出就退出。
异常
申明的错误应该抛出一个RuntimeException或者派生的异常。
顶层的main()函数应该截获所有的异常,并且打印(或者记录在日志中)在屏幕上。
3楼
垃圾收集
JAVA使用成熟的后台垃圾收集技术来代替引用计数。
但是这样会导致一个问题:
你必须在使用完对象的实例以后进行清场工作。
比如一个prel的程序员可能这么写:
...
FileOutputStreamfos=newFileOutputStream(projectFile);
project.save(fos,"
IDEProjectFile"
除非输出流一出作用域就关闭,非引用计数的程序语言,比如JAVA,是不能自动完成变量的清场工作的。
必须象下面一样写:
fos.close();
Clone
下面是一种有用的方法:
implementsCloneable
public
Objectclone()
{
ThisClassobj=(ThisClass)super.clone();
obj.field1=(int[])field1.clone();
obj.field2=field2;
}catch(CloneNotSupportedExceptione){
final类
绝对不要因为性能的原因将类定义为final的(除非程序的框架要求)
如果一个类还没有准备好被继承,最好在类文档中注明,而不要将她定义为final的。
这是因为没有人可以保证会不会由于什么原因需要继承她。
访问类的成员变量
大部分的类成员变量应该定义为protected的来防止继承类使用他们。
注意,要用"
int[]packets"
,而不是"
intpackets[]"
,后一种永远也不要用。
CounterSet(intsize)
编程技巧
byte数组转换到characters
为了将byte数组转换到characters,你可以这么做:
"
Helloworld!
.getBytes();
Utility类
Utility类(仅仅提供方法的类)应该被申明为抽象的来防止被继承或被初始化。
初始化
下面的代码是一种很好的初始化数组的方法:
objectArguments=newObject[]{arguments};
枚举类型
JAVA对枚举的支持不好,但是下面的代码是一种很有用的模板:
classColour{
publicstaticfinalColourBLACK=newColour(0,0,0);
publicstaticfinalColourRED=newColour(0xFF,0,0);
publicstaticfinalColourGREEN=newColour(0,0xFF,0);
publicstaticfinalColourBLUE=newColour(0,0,0xFF);
publicstaticfinalColourWHITE=newColour(0xFF,0xFF,0xFF);
这种技术实现了RED,GREEN,BLUE等可以象其他语言的枚举类型一样使用的常量。
他们可以用'
=='
操作符来比较。
但是这样使用有一个缺陷:
如果一个用户用这样的方法来创建颜色BLACK
newColour(0,0,0)
那么这就是另外一个对象,'
操作符就会产生错误。
她的equal()方法仍然有效。
由于这个原因,这个技术的缺陷最好注明在文档中,或者只在自己的包中使用。
Swing
避免使用AWT组件
混合使用AWT和Swing组件
如果要将AWT组件和Swing组件混合起来使用的话,请小心使用。
实际上,尽量不要将他们混合起来使用。
滚动的AWT组件
AWT组件绝对不要用JscrollPane类来实现滚动。
滚动AWT组件的时候一定要用AWTScrollPane组件来实现。
避免在InternalFrame组件中使用AWT组件
尽量不要这么做,要不然会出现不可预料的后果。
Z-Order问题
AWT组件总是显示在Swing组件之上。
当使用包含AWT组件的POP-UP菜单的时候要小心,尽量不要这样使用。
调试
调试在软件开发中是一个很重要的部分,存在软件生命周期的各个部分中。
调试能够用配置开、关是最基本的。
很常用的一种调试方法就是用一个PrintStream类成员,在没有定义调试流的时候就为null,类要定义一个debug方法来设置调试用的流。
性能
在写代码的时候,从头至尾都应该考虑性能问题。
这不是说时间都应该浪费在优化代码上,而是我们时刻应该提醒自己要注意代码的效率。
比如:
如果没有时间来实现一个高效的算法,那么我们应该在文档中记录下来,以便在以后有空的时候再来实现她。
不是所有的人都同意在写代码的时候应该优化性能这个观点的,他们认为性能优化的问题应该在项目的后期再去考虑,也就是在程序的轮廓已经实现了以后。
不必要的对象构造
不要在循环中构造和释放对象
使用StringBuffer对象
在处理String的时候要尽量使用StringBuffer类,StringBuffer类是构成String类的基础。
String类将StringBuffer类封装了起来,(以花费更多时间为代价)为开发人员提供了一个安全的接口。
当我们在构造字符串的时候,我们应该用StringBuffer来实现大部分的工作,当工作完成后将StringBuffer对象再转换为需要的String对象。
如果有一个字符串必须不断地在其后添加许多字符来完成构造,那么我们应该使用StringBuffer对象和她的append()方法。
如果我们用String对象代替StringBuffer对象的话,会花费许多不必要的创建和释放对象的CPU时间。
避免太多的使用synchronized关键字
避免不必要的使用关键字synchronized,应该在必要的时候再使用她,这是一个避免死锁的好方法。
可移植性
BorlandJbulider不喜欢synchronized这个关键字,如果你的断点设在这些关键字的作用域内的话,调试的时候你会发现的断点会到处乱跳,让你不知所措。
除非必须,尽量不要使用。
换行
如果需要换行的话,尽量用println来代替在字符串中使用"
\n"
。
你不要这样:
System.out.print("
Hello,world!
要这样:
System.out.println("
或者你构造一个带换行符的字符串,至少要象这样:
Stringnewline=System.getProperty("
line.separator"
Helloworld"
+newline);
PrintStream
PrintStream已经被不赞成(deprecated)使用,用PrintWrite来代替她。