Java程序开发规范提纲

1.   编码规范
3.1 Package的命名
Package的名字都由一个小写单词组成。单词只能由小写字母组成。

每个Package必须由：com.jutone.[project name].[module name]组成。

例如Jserver项目中：com.jutone.jserver.cpmanagement

Lottery项目中：com.jutone.lottery.sms

3.2 class和interface的命名
可以由一个或多个单词组成，每个单词的第一个字母必须大写，单词与单词之间不使用下划线连结。class和interface的单词组合后最终的意思为名词。

3.3 static final变量的命名
由一个或多个单词组成，变量的名字都大写，单词与单词之间使用下划线连结。变量的描述要完整，不允许缩写单词出现。变量的最终意思为名词。变量例如：

HIERARCHY_REQUEST_ERROR

3.4 class和interface成员变量的命名
由一个或多个单词组成，第一个单词全部小写，以后的单词的首写字母大写，单词与单词之间不使用下划线连结。变量中的单词允许缩写，缩写单词的字母都大写，不允许连续出现缩写的单词，首单词不允许缩写，缩写的单词必须在文件的开头注释中申明。变量的最终意思为名词。变量例如：

DOMString documentURL; //正确

long CPID; //错误，连续的缩写，并且首单词使用了缩写。

long contentProviderID;//正确

boolean isId;//错误，ID是缩写，因此应该用ID而不是Id，在www.w3.org中有这样的定义，但是在本公司内不采用这样的方法。

boolean isID;//正确

 

3.5 class和interface成员method的命名
由一个或多个单词组成，第一个单词全部小写，以后的单词的首写字母大写，单词与单词之间不使用下划线连结。命名中的单词允许缩写，缩写单词的字母都大写，不允许连续出现缩写的单词，首单词不允许缩写，缩写的单词必须在文件的开头注释中申明。命名的最终意思为动词。命名例如：

public void getContentsProviderID();//正确

public void getCPID();//错误，有连续的缩写。

public void getCPIdentity();//正确。

public void getContentsProviderId();//错误，ID为缩写，因此要全部大写，在www.w3.org中，这种方式被认可，但是在本公司不被认可。

3.6 在单元测试中的类命名规则
在单元测试中（动态白盒），测试类的命名方式是使用小写的test+原有的类名称。例如要测试Car类使用的测试类是testCar。

3.7在method中局部变量的命名
命名方式见3.4，为了保持一致，不特意采用匈牙利命名规范。

3.8数组的命名
byte[] buffer;

不是

byte buffer[];

2.   书写规范
4.1 javadoc的使用
// 表示注释一行，该注释不会被javadoc翻译到文档中，开发人员可以随意使用。

/*……..*/，注释若干行，该注释不会被javadoc翻译到文档中，开发人员可以随意使用。

/**…….*/，生成文档的注释，支持HTML文法。

4.1.1 class的javadoc
需要书写该类的说明，如类的描述，功能，类型，与其他类的交互等等。

/**

 * description

 */

4.1.2 attribute的javadoc
由于大部分的attribute为私有变量，所以不需要写在JAVADOC中，所以只需要用“//”来书写注释。

// description

4.1.3 method的javadoc
需要描述的有该方法的功能说明，接受的参数，返回值等等。

/**

     * The method is used for adding object.

     * @param EndUserInfo endUserInfo

     * @return int

     * success - 0

     * failed - -1

     */

4.2 文件头
/**

 * File: file name

 * Description:file description

 * @author author name

 * @version version NO.

 * Copyright: Copyright (c) 2003 Shanghai Jutone Electronics Ltd.

 */

4.3 文档中的注释
在每个类申明，类成员变量、类方法的申明前必须有文档注释。

文档注释只说明紧接其后的类、属性或方法。例如：

/** comment for class*/

public class Test

{

/**comment for an attribute*/

int number;

/**comment for a method*/

public void myMethod()

{
}

根据在文档中显示的效果，文档注释分为三部分。

4.3.1 简述
文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。例如：

/**

*[方法或属性的简述]

*/

4.3.2 详细说明
以下情况专门针对于某个方法内部。

所有的注释都在该行的上方用“//”来表示，后面接注释的内容。

 

注释的顺序为：

文件头顶格写在最上方。

空一行后写package

空一行写import

空一行写class的注释

方法的注释和上面空一行。

4.3.3 特殊部分
包括版本说明、参数说明、返回值说明等。

/**

*[方法或属性的简述]

*<p>[方法或属性的详细说明第一行]<br>

*[方法或属性的详细说明第二行]<br>

*@param […….]

*@return [……..]

*/

一些javadoc的标记

标记
 用于
 作用
 
@author
 对类的说明
 标明开发该类模块的作者
 
@version
 对类的说明
 标明该类模块的版本
 
@see
 对类、属性、方法的说明
 参考转向，也就是相关主题
 
@param
 对方法的说明
 对方法中某参数的说明
 
@return
 对方法的说明
 对方法返回值的说明
 
@exception
 对方法的说明
 对方法可能抛出的异常进行说明
 

下面详细说明各标记。

　　1. @see 的使用

　　@see 的句法有三种：

　　@see 类名

　　@see #方法名或属性名

　　@see 类名#方法名或属性名

　　类名，可以根据需要只写出类名 (如 String) 或者写出类全名 (如 java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？

　　如果 java 源文件中的 import 语句包含了的类，可以只写出类名，如果没有包含，则需要写出类全名。java.lang 也已经默认被包含了。这和 javac 编译 java 源文件时的规定一样，所以可以简单的用 javac 编译来判断，源程序中 javac 能找到的类，javadoc 也一定能找到；javac 找不到的类，javadoc 也找不到，这就需要使用类全名了。

方法名或者属性名，如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及参数类型，没有参数的方法，需要写出一对括号。如

成员类型
 成员名称及参数
 @see 句法
 
属性
 number
 @see number
 
属性
 count
 @see count
 
方法
 count()
 @see count()
 
方法
 show(boolean b)
 @see show(boolean)
 
方法
 main(String[] args)
 @see main(String[])
 

@see 的第二个句法和第三个句法都是转向方法或者属性的参考，它们有什么区别呢？

第二个句法中没有指出类名，则默认为当前类。所以它定义的参考，都转向本类中的属性或者方法。而第三个句法中指出了类名，则还可以转向其它类的属性或者方法。

关于 @see 标记，我们举个例说明。由于 @see 在对类说明、对属性说明、对方法说明时用法都一样，所以这里只以对类说明为例。

/**

* @see String

* @see java.lang.StringBuffer

* @see #str

* @see #str()

* @see #main(String[])

* @see Object#toString()

*/

public class TestJavaDoc

{

}

String 和 StringBuffer 都是在 java.lang 包中，由于这个包是默认导入了的，所以这两个类可以直接写类名，也可以写类全名。str、str() 为同名属性和方法，所以方法名需要用 () 区分。main 是带参数的方法，所以在 () 中指明了参数类型。toString() 虽然在本类中也有 (从 Object 继承的)，但我们是想参考 Object 类的 toString() 方法，所以使用了 Object#toString()。

　奇怪的是，为什么其中只有 str、str() 和 main(String[]) 变成了链接呢？那是因为编译时没有把 java.lang 包或者 Stirng、StringBuffer、Object 三个类的源文件一起加入编译，所以，生成的文档没有关于那三个类的信息，也就不可以建立链接了。

4.4 编码顺序
 

[package]

[import]

[文件头]

[一些附加说明，如缩写的表示等]

[类的注释]

[类的定义]

[类的成员变量的注释]

[类的成员变量的定义]

[类变量的存取方法的注释，指get, set]

[类变量的存取方法的定义]

[构造函数的注释]

[构造函数，参数多的写在后面，采用递增方式书写]

[克隆方法的注释]

[克隆方法的定义]

[类方法的注释]

[类方法的定义]

[类方法的实现体按照定义的顺序]

[main方法]

4.5 缩进
缩进应该是每行4个空格。不要在源文件中保存Tab字符. 在使用不同的源代码管理工具时Tab字符将因为用户设 置的不同而扩展为不同的宽度。如果你使用 UltraEdit 作为你的 Java 源代码编辑器的话，你可以通过如下操作来禁止 保存Tab字符, 方法是通 过 UltrEdit中先设定 Tab 使用的长度是4个空格，然后用Format|Tabs to Spaces 菜单将 Tab 转换为空格。

4.6 页宽
页宽应该设置为100字符。源代码一般不会超过这个宽度, 并导致无法完整显示, 但这一设置也可以灵活调整。在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行。一条语句折行后, 应该比原来的语句再缩进4个字符。

4.7 {} 对
{} 中的语句应该单独作为一行. 例如, 下面的第1行是错误的, 第2行是正确的:

if (i>0) { i ++ }; // 错误, { 和 } 在同一行

if (i>0)

{

i ++

}; // 正确, { 单独作为一行

} 语句永远单独作为一行。

如果 } 语句应该缩进到与其相对应的 { 那一行相对齐的位置。

4.8 括号
左括号和后一个字符之间不应该出现空格, 同样, 右括号和前一个字符之间也不应该出现空格. 下面的例子说明 括号和空格的错误及正确使用:

CallProc( AParameter ); // 错误

CallProc(AParameter); // 正确

不要在语句中使用无意义的括号. 括号只应该为达到某种目的而出现在源代码中。下面的例子说明错误和正确的 用法:

if ((I) = 42) { // 错误，括号毫无意义

if (I == 42 ||J == 42) // 正确，的确需要括号

4.9 程序编写规范
4.9.1 方法的程序行数
尽管不能以在每个方法中程序行数来判断代码质量的好坏，但是在大多数情况下，在一个方法实现中超过100行代码的方法多数不是质量优秀的代码，因此在本公司每个方法的实现不能超过100行。超过100行的方法需要分拆成若干个方法。

4.9.2 exit()
exit 除了在 main 中可以被调用外，其他的地方不应该调用。因为这样做不给任何代码代码机会来截获退出。一个类似后台服务地程序不应该因为某一个库模块决定了要退出就退出。

4.9.3 异常
申明的错误应该抛出一个RuntimeException或者派生的异常。

顶层的main()函数应该截获所有的异常，并且打印（或者记录在日志中）在屏幕上。

4.9.4 垃圾收集
JAVA使用成熟的后台垃圾收集技术来代替引用计数。但是这样会导致一个问题：你必须在使用完对象的实例以后 进行清场工作。比如一个perl的程序员可能这么写：

...

{

FileOutputStream fos = new FileOutputStream(projectFile);

project.save(fos, "IDE Project File");

}

...

除非输出流一出作用域就关闭，非引用计数的程序语言，比如JAVA，是不能自动完成变量的清场工作的。必须象下面一样写：

FileOutputStream fos = new FileOutputStream(projectFile);

project.save(fos, "IDE Project File");

fos.close();

4.9.5 Clone
下面是一种有用的方法：

implements Cloneable

public

Object clone()

{

try

{

ThisClass obj = (ThisClass)super.clone();

obj.field1 = (int[])field1.clone();

obj.field2 = field2;

return obj;

} catch(CloneNotSupportedException e)

{

throw new InternalError("Unexpected CloneNotSUpportedException: " + e.getMessage());

}

}

4.9.6 final 类
绝对不要因为性能的原因将类定义为 final 的（除非程序的框架要求）

如果一个类还没有准备好被继承，最好在类文档中注明，而不要将她定义为 final 的。这是因为没有人可以保 证会不会由于什么原因需要继承她。

4.9.7 访问类的成员变量
大部分的类成员变量应该定义为 private 的来防止继承类使用他们。

注意，要用"int[] packets"，而不是"int packets[]"，后一种永远也不要用。

public void setPackets(int[] packets)

{

this.packets = packets;

}

CounterSet(int size)

{

this.size = size;

}

4.10 编程技巧
4.10.1 byte 数组转换到 characters
为了将 byte 数组转换到 characters，你可以这么做：

"Hello world!".getBytes();

4.10.2 Utility 类
Utility 类（仅仅提供方法的类）应该被申明为抽象的来防止被继承或被初始化。

4.10.3 初始化
下面的代码是一种很好的初始化数组的方法：

objectArguments = new Object[] {arguments };

4.10.4 枚举类型
JAVA 对枚举的支持不好，但是下面的代码是一种很有用的模板：

class Colour

{

public static final Colour BLACK = new Colour(0, 0, 0);

public static final Colour RED = new Colour(0xFF, 0, 0);

public static final Colour GREEN = new Colour(0, 0xFF, 0);

public static final Colour BLUE = new Colour(0, 0, 0xFF);

public static final Colour WHITE = new Colour(0xFF, 0xFF, 0xFF);

}

这种技术实现了RED, GREEN, BLUE 等可以象其他语言的枚举类型一样使用的常量。他们可以用 '==' 操作符来 比较。但是这样使用有一个缺陷：如果一个用户用这样的方法来创建颜色 BLACK

new Colour(0,0,0)

那么这就是另外一个对象，'=='操作符就会产生错误。她的 equal() 方法仍然有效。由于这个原因，这个技术的缺陷最好注明在文档中，或者只在自己的包中使用。

4.10.5 Swing
避免使用 AWT 组件混合使用 AWT 和 Swing 组件，如果要将 AWT 组件和 Swing 组件混合起来使用的话，请小心使用。实际上，尽量不

要将他们混合起来使用。

4.10.6 滚动的 AWT 组件
AWT 组件绝对不要用 JscrollPane 类来实现滚动。滚动 AWT 组件的时候一定要用AWT ScrollPane 组件来实 现。

 

避免在 InternalFrame 组件中使用 AWT 组件

尽量不要这么做，要不然会出现不可预料的后果。

4.10.7 Z-Order 问题
AWT 组件总是显示在 Swing 组件之上。当使用包含 AWT 组件的 POP-UP 菜单的时候要小心，尽量不要这样使用。

4.11 调试
调试在软件开发中是一个很重要的部分，存在软件生命周期的各个部分中。调试能够用配置开、关是最基本的。

很常用的一种调试方法就是用一个 PrintStream 类成员，在没有定义调试流的时候就为null，类要定义一 个 debug 方法来设置调试用的流。

4.12 性能
在写代码的时候，从头至尾都应该考虑性能问题。这不是说时间都应该浪费在优化代码上，而是我们时刻应该提 醒自己要注意代码的效率。比如：如果没有时间来实现一个高效的算法，那么我们应该在文档中记录下来，以便 在以后有空的时候再来实现她。

不是所有的人都同意在写代码的时候应该优化性能这个观点的，他们认为性能优化的问题应该在项目的后期再去考虑，也就是在程序的轮廓已经实现了以后。

4.12.1不必要的对象构造
不要在循环中构造和释放对象

4.12.2 使用 StringBuffer 对象
在处理 String 的时候要尽量使用 StringBuffer 类，StringBuffer 类是构成 String类的基础。String类将StringBuffer类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用StringBuffer来实现大部分的工作，当工作完成后将StringBuffer对象再转换为需要的String对象。

比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用StringBuffer对象和她的append()方法。如果我们用 String 对象代替 StringBuffer对象的话，会花费许多不必要的创建和释放对象的 CPU 时间。

4.12.3 避免太多的使用 synchronized 关键字
避免不必要的使用关键字 synchronized，应该在必要的时候再使用她，这是一个避免死锁的好方法。

4.13 可移植性
4.13.1 换行
如果需要换行的话，尽量用 println 来代替在字符串中使用"\n"。

你不要这样：

System.out.print("Hello,world!\n");

要这样：

System.out.println("Hello,world!");

或者你构造一个带换行符的字符串，至少要象这样：

String newline = System.getProperty("line.separator");

System.out.println("Hello world" + newline);

4.13.2 PrintStream
PrintStream 已经被不赞成（deprecated）使用，用 PrintWrite 来代替她

本文来自CSDN博客，转载请标明出处：http://blog.csdn.net/huaiyuren/archive/2009/04/23/4103998.aspx