JAVA程序编码要求规范Word文档格式.docx
《JAVA程序编码要求规范Word文档格式.docx》由会员分享,可在线阅读,更多相关《JAVA程序编码要求规范Word文档格式.docx(16页珍藏版)》请在冰豆网上搜索。
*/
行注释:
主要用在方法部,对代码,变量,流程等进行说明。
与块注释格式相似,但是整个注释占据一行。
/*注释*/
尾随注释:
与行注释功能相似,放在代码的同行,但是要与代码之间有足够的空间,便于分清。
intm=4;
/*注释*/
如果一个程序块有多个尾随注释,每个注释的缩进应该保持一致。
行尾注释:
与行注释功能相似,放在每行的最后,或者占据一行。
以‘//’开头。
文档注释:
与块注释相似,但是可以被javadoc处理,生成HTML文件。
以‘/**’开头,‘*/’结尾。
问挡住是不能放在方法或程序块。
/**
1.11注释那些部分
项目
注释哪些部分
实参/
参数
参数类型
参数用来做什么
任何约束或前提条件
示例
字段/
字段/属性
字段描述
注释所有使用的不变量
并行事件
可见性决策
类
类的目的
已知的问题
类的开发/维护历史
注释出采用的不变量
并行策略
编译单元
每一个类/类定义的接口,含简单的说明
文件名和/或标识信息
信息
接口
目的
它应如何被使用以及如何不被使用
局部变量
用处/目的
成员函数注释
成员函数做什么以及它为什么做这个
哪些参数必须传递给一个成员函数
成员函数返回什么
任何由某个成员函数抛出的异常
成员函数是如何改变对象的
包含任何修改代码的历史
如何在适当情况下调用成员函数的例子适用的前提条件和后置条件
成员函数部注释
控制结构
代码做了些什么以及为什么这样做
难或复杂的代码
处理顺序
2命名
2.1命名的基本约定
一般应该使用可以准确说明变量/字段/类的完整的英文描述符,如firstName。
对一些作用显而易见的变量可以采用简单的命名,如在循环里的递增(减)变量就可以被命名为”i”。
尽量采用项目所涉及领域的术语。
可以采用大小写混合,提高名字的可读性。
尽量少用缩写,但如果一定要使用,就要谨慎地使用。
同时,应该保留一个标准缩写的列表,并且在使用时保持一致。
避免使用长名字(最好不超过15个字母)。
避免使用相似或者仅在大小写上有区别的名字。
避免使用下划线作为名字的首末字母。
2.2标识符的命名约定
标示符类型
命名约定
例子
包
全部小写。
标识符用点号分隔开来。
为了使包的名字更易读,Sun公司建议包名中的标识符用点号来分隔。
Sun公司的标准java分配包用标识符.java开头。
全局包的名字用你的机构的Internet保留域名开头。
局部包:
interface.screens
全局包:
.rational..interface.screens
类,接口
类的名字应该使用名词。
每个单词第一个字母应该大写。
避免使用单词的错写,除非它的缩写已经广为人知,如HTTP。
ClassHello;
ClassHelloWorld;
InterfaceApple;
方法
第一个单词一般是动词。
第一个字母是小些,但是中间单词的第一个字母是大写。
如果方法返回一个成员变量的值,方法名一般为get+成员变量名,如若返回的值是bool变量,一般以is作为前缀。
如果方法修改一个成员变量的值,方法名一般为:
set+成员变量名。
getName();
setName();
isFirst();
变量
第一个字母小写,中间单词的第一个字母大写。
不要用_或&
作为第一个字母。
尽量使用短而且具有意义的单词。
单字符的变量名一般只用于生命期非常短暂的变量。
i,j,k,m,n一般用于integers;
c,d,e一般用于characters。
如果变量是集合,则变量名应用复数。
命名组件采用匈牙利命名法,所有前缀均应遵循同一个组件名称缩写列表。
StringmyName;
inti;
intn;
charc;
int[]students;
btNew;
(bt是Button的缩写)
常量
所有常量名均全部大写,单词间以‘_’隔开。
intMAX_NUM;
3声明
每行应该只有一个声明。
局部变量必须初始化。
除了for循环外,声明应该放在块的最开始部分。
for循环中的变量声明可以放在for语句中。
for(inti=0;
i<
10;
i++)。
避免块部的变量与它外部的变量名相同。
表达式和语句
3.1每行应该只有一条语句。
3.2if-else
if-elseif语句,任何情况下,都应该有“{”,“}”,格式如下:
if(condition)
statements;
}
elseif(condition)
else
}
3.3for语句
格式如下:
for(initialization;
condition;
update)
如果语句为空:
for(initialization;
update);
3.4while语句
while(condition)
如果语句为空:
while(condition);
3.5do-while语句
do
while(condition);
3.6switch语句
每个switch里都应包含default子语句,格式如下:
switch(condition)
caseABC:
/*fallsthrough*/
caseDEF:
break;
caseXYZ:
default:
3.7try-catch语句
try
catch(ExceptionClasse)
finally
4错误处理和异常事件
通常的思想是只对错误采用异常处理:
逻辑和编程错误,设置错误,被破坏的数据,资源耗尽,等等。
通常的法则是系统在正常状态下以及无重载和硬件失效状态下,不应产生任何异常。
异常处理时可以采用适当的日志机制来报告异常,包括异常发生的时刻。
不要使用异常实现来控制程序流程结构。
可移植性
4.1尽量不要使用已经被标为不赞成使用的类或方法。
4.2代码应遵循UNIX风格。
4.3如果需要换行的话,尽量用println来代替在字符串中使用"
\n"
。
4.4用separator()方法代替路径中的”/”或”\”。
4.5用pathSeptarator()方法代替路径中的”:
”或”;
”。
5Java
文件样式
所有的
Java(*.java)
文件都必须遵守如下的样式规则
5.1信息
信息必须在
java
文件的开头,比如:
*<
p>
Title:
本文件的标题<
/p>
Description:
对本文件的描述<
Copyright:
信息<
Company:
公司名称<
*author作者Email
*version版本号
*/
其他不需要出现在
javadoc
的信息也可以包含在这里。
5.2Package/Imports
package
行要在
import
行之前,import
中标准的包名要在本地的包名之前,而且按照字母顺序排列。
如果
行中包含了同一个包中的不同子目录,则应该用
*
来处理。
.stats;
java.io.*;
java.util.Observable;
hotlava.util.Application;
这里
java.io.*
使用来代替InputStream
and
OutputStream
的。
5.3Class
接下来的是类的注释,一般用来解释类的作用。
A
class
representing
a
set
of
packet
byte
counters
It
is
observable
to
allow
it
be
watched,
but
only
reports
changes
when
the
current
complete
接下来是类定义,包含了在不同的行的
extends
和
implements
一般应遵循extends在前,implements在后的原则。
public
CounterSet
extends
Observable
implements
Cloneable
5.4Class
Fields
接下来是类的成员变量:
Packet
protected
int[]
packets;
的成员变量必须生成文档(JavaDoc)。
proceted、private和
定义的成员变量如果名字含义明确的话,可以没有注释。
5.5存取方法
接下来是类变量的存取的方法。
它只是简单的用来将类的变量赋值获取值的话,可以简单的写在一行上。
Get
return
an
array
containing
statistical
data.
This
has
been
freshly
allocated
can
modified
by
caller.
getPackets()
{
copyArray(packets,
offset);
getBytes()
copyArray(bytes,
void
setPackets(int[]
packets)
this.packets
=
其它的方法不要写在一行上。
5.6构造函数
接下来是构造函数,它应该用递增的方式写(比如:
参数多的写在后面)。
访问类型
("
public"
"
private"
等.)
任何
static"
final"
或
synchronized"
应该在一行中,并且方法和参数另写一行,这样可以使方法和参数更易读。
publicstatic
CounterSet(int
size)
this.size
size;
5.7克隆方法
如果这个类是可以被克隆的,那么下一步就是
clone
方法:
publicObject
clone()
try
{
CounterSet
obj
(CounterSet)super.clone();
obj.packets
(int[])packets.clone();
obj.size
obj;
catch(CloneNotSupportedException
e)
throw
new
InternalError("
Unexpected
CloneNotSUpportedException:
+
e.getMessage());
5.8类方法
下面开始写类的方法:
/**
*Createsanewzipentrywiththespecifiedname.
*
*paramnametheentryname
*exceptionNullPointerExceptioniftheentrynameisnull
*exceptionIllegalArgumentExceptioniftheentrynameislongerthan
*0xFFFFbytes
publicZipEntry(Stringname)
if(name==null)
thrownewNullPointerException();
}
if(name.length()>
0xFFFF)
thrownewIllegalArgumentException("
entrynametoolong"
);
this.name=name;
5.9toString
无论如何,每一个类都应该定义
toString
publicString
toString()
String
retval
CounterSet:
;
for
(int
i
0;
<
data.length();
i++)
+=
data.bytes.toString();
data.packets.toString();
retval;
5.10main
方法
如果main(String[])
方法已经定义了,
那么它应该写在类的底部.
程序编写规
5.11exit()
exit
除了在
main
中可以被调用外,其他的地方不应该调用。
因为这样做不给任何代码代码机会来截获退出。
一个类似后台服务地程序不应该因为某一个库模块决定了要退出就退出。
异常
申明的错误应该抛出一个RuntimeException或者派生的异常。
顶层的main()函数应该截获所有的异常,并且打印(或者记录在日志中)在屏幕上。
5.12垃圾收集
JAVA使用成熟的后台垃圾收集技术来代替引用计数。
但是这样会导致一个问题:
你必须在使用完对象的实例以后进行清场工作。
比如一个prel的程序员可能这么写:
...
FileOutputStream
fos
FileOutputStream(projectFile);
project.save(fos,
IDE
Project
File"
除非输出流一出作用域就关闭,非引用计数的程序语言,比如JAVA,是不能自动完成变量的清场工作的。
必须象下面一样写:
fos.close();
5.13Clone
下面是一种有用的方法:
Cloneable
clone()
ThisClass
(ThisClass)super.clone();
obj.field1
(int[])field1.clone();
obj.field2
field2;
}
e.getMessage());
5.14final
类
绝对不要因为性能的原因将类定义为
final
的(除非程序的框架要求)
如果一个类还没有准备好被继承,最好在类文档中注明,而不要将她定义为
这是因为没有人可以保证会不会由于什么原因需要继承她。
5.15访问类的成员变量
大部分的类成员变量应该定义为
的来防止继承类使用他们。
注意,要用"
packets"
,而不是"
int
packets[]"
,后一种永远也不要用。
6编程技巧
6.1byte
数组转换到characters
为了将
数组转换到
characters,你可以这么做:
Hello
world!
.getBytes();
6.2Utility
Utility
类(仅仅提供方法的类)应该被申明为抽象的来防止被继承或被初始化。
6.3初始化
下面的代码是一种很好的初始化数组的方法:
objectArguments
Object[]
arguments
6.4枚举类型
JAVA
对枚举的支持不好,但是下面的代码是一种很有用的模板:
Colour
static
BLACK
Colour(0,
0,
0);
RED
Colour(0xFF,
GREEN
0xFF,
BLUE
0xFF);
WHITE
这种技术实现了RED,
GREEN,
等可以象其他语言的枚举类型一样使用的常量。
他们可以用
'
=='
操作符来比较。
但是这样使用有一个缺陷:
如果一个用户用这样的方法来创建颜色
Colour(0,0,0)
那么这就是另外一个对象,'
操作符就会产生错误。
她的
equal()
方法仍然有效。
由于这个原因,这个技术的缺陷最好注明在文档中,或者只在自己的包中使用。
6.5Swing
避免使用
AWT
组件
混合使用
Swing
如果要将
组件和
组件混合起来使用的话,请小心使用。
实际上,尽量不要将他们混合起来使用。
滚动的
组件绝对不要用
JscrollPane
类来实现滚动。
滚动
组件的时候一定要用
ScrollPane
组件来实现。
避免在
InternalFrame
组件中使用
尽量不要这么做,要不然会出现不可预料的后果。
Z-Order
问题
组件总是显示在
组件之上。
当使用包含
组件的
POP-UP
菜单的时候要小心,尽量不要这样使用。
6.6调试
调试在软件开发中是一个很重要的部分,存在软件生命周期的各个部分中。
调试能够用配置开、关是最基本的。
很常用的一种调试方法就是用一个
PrintStream
类成员,在没有定义调试流的时候就为
null,类要定义一个
debug
方法来设置调试用的流。
6.7性能
在写代码的时候,从头至尾都应该考虑性能问题。
这不是说时间都应该浪费在优化代码上,而是我们时刻应该提醒自己要注意代码的效率。
比如:
如果没有时间来实现一个高效的算法,那么我们应该在文档中记录下来,以便在以后有空的时候再来实现她。
不是所有的人都同意在写代码的时候应该优化性能这个观点的,他们认为性能优化的问题应该在项目的后期再去考虑,也就是在程序的轮廓已经实现了以后。
不必要的对象构造
不要在循环中构造和释放对象
6.8使用
StringBuffer
和StringBuilder对象
在处理
String
的时候要尽量使用
类,StringBuffer
类是构成