Java编程规范(草案).doc

1、YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 1 页 共 29 页 撰写人：开发中心文档编号： 版本编号：1.0.0银海构建化集成应用平台编程规范（草案）文档类别： 软件开发过程规范文档编号：当前版本： 1.0.0作 者： 开发中心文件状态： 草案 正式发布 正在修改完成日期： 2006-10-1银海软件YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 2 页 共 29 页 撰写人：开发中心版 本 历

2、 史版本/状态 作者 参与者 起止日期 备注1.0.0 开发中心YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 3 页 共 29 页 撰写人：开发中心目 录JAVA 编程规范 11. 引言 52. 命名规则 53. Java 文件样式 .63.1. 版权信息 63.2. Package/Imports.73.3. Class .74. 代码编写格式 104.1. 代码样式 104.2. 文档化 104.3. 缩进 114.4. 页宽 114.5. 注释 124.5.1. 目的 .124.5.2.

3、场景 .124.5.3. 要求 .134.6. 其他 144.6.1. 一行只写一个语句 .144.6.2. 空行使用 .144.6.3. 空格使用 .144.6.4. 对 .154.6.5. 括号 .154.6.6. 语句和表达式的参照格式 .154.7. Jbuilder 的格式设置 175. 程序编写规范 205.1. main() .205.2. exit() .215.3. 异常 215.4. 垃圾收集 215.5. Clone 215.6. final 类 225.7. 访问类的成员变量 226. 编程技巧 226.1. 设计类和方法 226.2. 继承的选择 236.3. 作用域

4、 236.4. “伪功能” 246.5. 不必要的对象构造 246.6. interfaces 和 abstract class .246.7. 变量 246.8. 避免使用“魔术数字” 256.9. byte 数组转换到 characters.25YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 4 页 共 29 页 撰写人：开发中心6.10. Utility 类 .256.11. 初始化 .256.12. 枚举类型 .256.13. Swing.266.14. 性能 .266.15. 使用 St

5、ringBuffer 对象 .266.16. 避免太多的使用 synchronized 关键字 276.17. 换行 .276.18. PrintStream 276.19. 数值计算 .276.20. finalize().286.21. 对象集合 .286.22. constructor .286.23. 循环 .28YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 5 页 共 29 页 撰写人：开发中心1. 引言本规范定义一个源码级应用程序的开发规范，它是借助 java 程序语言，以 Ecli

6、pse 开发环境为例提供的标准化服务。它可供应用开发人员及系统设计人员使用。本规范描述开发人员关心的外部特性及设施，而不是描述为达到这些功能采用的内部结构技术。适用于公司中所有使用 java 作为程序开发语言进行的产品和项目的应用开发。2. 命名规则为了让项目中所有的文档具有一致性的，增加可读性，保证产品和项目的可维护性，在命名时用英文为类或方法等赋予表义性强的名字。比如方法名 doIt、getIt 的可读性很难与 calculateSalesTax、retrieveByUserID 相比。给正确的命名，可使程序工程的调试和维护工作大大的改观。认真对待方法命名的工作，不要为了减少键入操作量而降

7、低可理解度。除了广为人知通用的和公司专门作了规定的单词以外，不要自行使用缩写，由缩写方法名组成的代码很难理解和维护。 Package包（Package）的命名用点号来分隔，全都都是小写名词，即便中间的单词亦是如此。对于域名扩展名称，如 com，org，net 或者 edu 等，全部都应小写（这也是 Java 1.1 和Java 1.2 的区别之一） 。 Class/Interface类/接口（class/interface ）名必须由大写字母开头而其他字母都小写用名词组成。例如：ClassName通用的类名(文件)包括： 抽象类 AbstractClassName 实现类 InterfaceN

8、ameImpl 缺省实现类 DefaultInterfaceNameImpl 工具类 ClassNameUtil 变量变量一般使用名词，首字母小写，大写中间单词的首字母。例如： fieldName 不要用_或 数组数组应该总是用这种方式来命名：byte buffer 而不是： byte buffer；3. Java 文件样式所有的 Java(*.java) 文件都必须遵守如下的样式规则（严格按以下顺序组织各部分） 。3.1.版权信息版权信息必须在 java 文件的开头，其他不需要出现在 javadoc 的信息也可以包含在这里。比如： /*YINHAI SOFTWARE 撰写日期：2004 年

9、11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 7 页 共 29 页 撰写人：开发中心* XMLHelper.java* 版本 :1.0.0* 日期 :2004-11-15* Copyright 2004 YINHAI Software Co. Ltd.* All right reserved.*/3.2.Package/Importspackage 行要在 import 行之前，import 的包或类先按 JDK 标准包、JDK 扩展包、第三方包、公共包名、本地应用包顺序，再按照字母顺序排列。如果 import 行中包含了同一个包中的不同子目录，则应

10、该用 * 来处理。比如：package .stats; import java.io.*; import java.util.Observable; import hotlava.util.Application;这里 java.io.* 使用来代替 InputStream and OutputStream 的。 3.3.Class 每个 Java 源文件包含一个单一的 public class 或 interface。 当 private class 及interface 与 public class 相关联时，可将它们放在同一个源文件中作为 private class。 public cl

11、ass 应当是文件中的第一个 class 及 interface。 类注释类的注释一般是用来解释类的，比如：/* * 辅助解析 XML 文件， * author * version .*/ 类定义接下来是类定义，包含了在不同的行的 extends 和 implements public class CounterSet extends Observable implements Cloneable YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 8 页 共 29 页 撰写人：开发中心 类变量pub

12、lic 的变量必须有注释生成文档（JavaDoc ） ，proceted 、 private 和 package 定义的成员变量如果名字含义明确的话，可以没有注释。例如：/* * 姓名*/ protected String name; 类变量必须按 static final 变量、static non-final 变量、成员变量的顺序声明 构造方法 构造方法应该用递增的方式写（比如：参数多的写在后面）作用域(“public ”， “private” 等) 和 任何 “static”， “final” 或“synchronized”及方法和参数写在一行中，如果列宽超过 80，参数可以折行。例如：

13、public People(String name, String sex, Date birthday ) this. name = name; this. sex = sex; this. birthday = birthday; 类方法类方法要按照 public、protected、private 的排序，以下是一个方法的示例： /* * Set the packet counters * (such as when restoring from a database) * param r1 * param r2 * param r3 * param r4 */ protected fi

14、nal void setArray(int r1， int r2， int r3， int r4)throws IllegalArgumentException / / Ensure the arrays are of equal size / if (r1.length != r2.length | r1.length != r3.length | r1.length != r4.length)throw new IllegalArgumentException(“Arrays must be of the same size“);System.arraycopy(r1， 0， r3， 0，

15、 r1.length); YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 9 页 共 29 页 撰写人：开发中心System.arraycopy(r2， 0， r4， 0， r1.length); 存取方法它只是简单的用来将类的变量赋值获取值的话，可以简单的写在一行上。 /* * 获取姓名* return 雇员姓名。 */public String getName() return name; /* * 设置姓名* param sex 雇员姓名。 */public void setSex(Stri

16、ng sex) this.sex = sex; 其它的方法不要写在一行上 克隆方法如果这个类是可以被克隆的，那么下一步就是 clone 方法：public Object clone() try People obj = (People)super.clone(); obj. name = name; obj. sex = sex; this. birthday = birthday; catch(CloneNotSupportedException e) finalize()public void finalize() toString 方法无论如何，每一个类都应该定义 toString 方法

17、： public String toString() String retval = “CounterSet： “; for (int i = 0; i 0) i + ; / 错误， 和 在同一行 if (i0) i + ; / 正确， 单独作为一行 语句永远单独作为一行， 语句应该缩进到与其相对应的 那一行相对齐的位置。 4.6.5. 括号左括号和后一个字符之间不应该出现空格， 同样， 右括号和前一个字符之间也不应该出现空格。下面的例子说明括号和空格的错误及正确使用： CallProc( AParameter ); / 错误 CallProc(AParameter); / 正确 不要在语句中

18、使用无意义的括号。括号只应该为达到某种目的而出现在源代码中。下面的例子说明错误和正确的用法： if (I) = 42) / 错误 - 括号毫无意义 if (I = 42) | (J = 42) )then / 正确 - 的确需要括号 4.6.6. 语句和表达式的参照格式 if-else，if-elseif 语句，任何情况下，都应该有“ ”， “”，格式如下：if (condition) statements; else if (condition) statements; elsestatements; for 语句格式如下：for (initialization; condition; up

19、date) YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 16 页 共 29 页 撰写人：开发中心statements;如果语句为空：for (initialization; condition; update) ; while 语句格式如下：while (condition) statements;如果语句为空：while (condition); do-while 语句格式如下：do statements; while (condition); switch 语句，每个 switch 里都应

20、包含 default 子语句，格式如下：switch (condition) case ABC：statements;/* falls through */case DEF：statements;break;case XYZ：statements;break;default：statements;break; try-catch 语句格式如下：try statements; catch (ExceptionClass e) statements; finally statements;YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2

21、018 年 09 月 11 日 第 17 页 共 29 页 撰写人：开发中心4.7.Jbuilder 的格式设置在使用 Jbuilder 时请将工程的格式按如下设置：YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 18 页 共 29 页 撰写人：开发中心YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 19 页 共 29 页 撰写人：开发中心YINHAI SOFTWARE 撰写日期：2004 年 11

22、月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 20 页 共 29 页 撰写人：开发中心5. 程序编写规范5.1.main()对于自己创建的每一个类，都考虑置入一个 main()，其中包含了用于测试那个类的代YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 21 页 共 29 页 撰写人：开发中心码。为使用一个项目中的类，我们没必要删除测试代码。若进行了任何形式的改动，可方便地返回测试。这些代码也可作为如何使用类的一个示例使用。5.2.exit() exit 除了

23、在 main 中可以被调用外，其他的地方不应该调用。因为这样做不给任何代码机会来截获退出。一个类似后台服务的程序不应该因为某一个库模块决定了要退出就退出。 5.3.异常 申明的错误应该抛出一个 RuntimeException 或者派生的异常。 顶层的 main()函数应该截获所有的异常，并且打印（或者记录在日志中）在屏幕上。 5.4.垃圾收集 JAVA 使用成熟的后台垃圾收集技术来代替引用计数。但是这样会导致一个问题：比如一个 perl 的程序员可能这么写： FileOutputStream fos = new FileOutputStream(projectFile); project.s

24、ave(fos， “IDE Project File“); 而非引用计数的程序语言，比如 JAVA，是不能自动完成某些资源的清除工作的。必须在使用完对象的实例以后进行清除工作，需要象下面一样写： FileOutputStream fos = new FileOutputStream(projectFile); project.save(fos， “IDE Project File“); fos.close(); /显示关闭在一个特定的作用域内，若一个对象必须清除（非由垃圾收集机制处理） ，考虑到异常情况请采用下述方法：初始化对象；若成功，则立即进入一个含有 finally 从句的 try 块，

25、在 finally 中开始清除工作。5.5.Clone 在实现 Cloneable 接口时下面是一种有用的方法： YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 22 页 共 29 页 撰写人：开发中心public Object clone() try ThisClass obj = (ThisClass)super.clone(); obj.field1 = (int)field1.clone(); obj.field2 = field2; return obj; catch(CloneNotS

26、upportedException e) 5.6.final 类绝对不要因为性能的原因将类定义为 final 的（除非程序的框架要求）如果一个类还没有准备好被继承，最好在类文档中注明，而不要将她定义为 final 的。这是因为没有人可以保证会不会由于什么原因需要继承她。 5.7.访问类的成员变量大部分的类成员变量应该定义为 private 的来防止继承类使用他们。5.8.JAVA 中与数据库的数据类型对照数据库型 特性说明 JAVA 型VARCHAR2 java.lang.StringVARCHAR java.lang.StringCHAR java.lang.StringNUMBER int

27、Length 18 java.math.BigDecimalNUMBERintLength = 10java.lang.LongYINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 23 页 共 29 页 撰写人：开发中心NUMBER intScale 0 java.math.BigDecimalDATE java.sql.TimestampDATETIME java.sql.TimestampBLOB oracle.sql.BLOBIMAGE byte其它 java.lang.String6. 编程技

28、巧6.1.设计类和方法方法的重要性往往比类的重要性更容易理解，方法是指执行一个统一函数的一段代码。类常被错误的视为是一个仅仅用于存放方法的容器。有些开发人员甚至把这种思路作了进一步的发挥，将他们的所有方法放入单个类之中。类应该用来将相关的方法组织在一起，当类包含一组紧密关联的方法时，该类可以说具有强大的内聚力。当类包含许多互不相关的方法时，该类便具有较弱的内聚力。应该努力创建内聚力比较强的类。其次类要尽可能短小精悍，而且只解决一个特定的问题。下面是对类设计的一些建议： 一个复杂的开关语句考虑采用“多态”机制 。 如果数量众多的方法涉及到类型差别极大的操作考虑用几个类来分别实现 。 如果许多成员

29、变量在特征上有很大的差别考虑使用几个类。 要限制一个类中代码的长度。可以把较大的类方法抽取出来作为单独的类来实现，对于类中易变的部分也应该作相应的分离操作，这样对于程序的可读性和可维护性都是很有好处的。 任何时候只要发现类与类之间结合得非常紧密，就需要考虑是否采用内部类，从而改善编码及维护工作 大多数工程都包含许多并不十分适合与其他方法组合在一起的方法。在这种情况下，可以为这些不合群的方法创建一个综合性收容类。 尽量避免使用类变量。 每个方法都应执行一项特定的任务，它应出色的完成这项任务，要避免创建执行许多不同任务的方法。YINHAI SOFTWARE 撰写日期：2004 年 11 月 15

30、日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 24 页 共 29 页 撰写人：开发中心 创建方法时，方法应依靠参数而不应依靠全局变量，要设法将每个方法视为一个黑箱，其他部分不应要求了解该方法的内部工作情况，该方法也不应要求了解它外面的情况。 应将方法设计成简要的、功能性单元，用它描述和实现一个不连续的类接口部分。理想情况下，方法应简明扼要。若长度很大，可考虑通过某种方式将其分割成较短的几个方法。这样做也便于类内代码的重复使用（有些时候，方法必须非常大，但它们仍应只做同样的一件事情） 。 6.2.继承的选择在现成类的基础上创建新类时，请首先选择“新建” 。只有自己的设

31、计要求必须继承时，才应考虑这方面的问题。若在本来允许新建的场合使用了继承，则整个设计会变得没有必要地复杂。 6.3.作用域始终都应显式地定义作用域，而且让一切东西都尽可能地“私有”-private。可使库的某一部分非“公共化” （一个方法、类或者一个字段等等） ，就永远不能把它拿出。若强行拿出，就可能破坏其他人现有的代码，使他们不得不重新编写和设计。若只公布自己必须公布的，就可放心大胆地改变其他任何东西。在多线程环境中，隐私是特别重要的一个因素，只有 private 字段才能在非同步使用的情况下受到保护。6.4.“伪功能”用合理的设计方案消除“伪功能” 。也就是说，比如只需要创建类的一个对象，

32、就不要提前限制自己的应用程序，并加上一条“只生成其中一个”注释。请考虑将其封装成一个“单例”的形式。若在主程序里有大量散乱的代码，用于创建自己的对象，请考虑采纳一种创造性的方案，将些代码封装起来。 YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 25 页 共 29 页 撰写人：开发中心6.5.不必要的对象构造不要在循环中构造和释放对象 。6.6.interfaces 和 abstract class尽量使用 interfaces，少使用 abstract class。若已知某样东西准备成为一个基础

33、类，那么第一个选择应是将其变成一个 interface（接口） 。只有在不得不使用方法定义或者成员变量的时候，才需要将其变成一个 abstract（抽象）类。接口主要描述了客户希望做什么事情，而一个类则致力于（或允许）具体的实现细节。 6.7.变量 用于多个目的的变量称为无焦点（多焦点）的变量。无焦点变量所代表的意义与程序的执行流程有关，当程序处于不同位置时，它所表示的意义是不固定的，这样就给程序的可读性和可维护性带来了麻烦。 最好在声明局部变量的地方即做变量的初始化。 （唯一的例外是：如果初始值是先由其他计算得出的的时候，不在声明的地方做变量初始化） 在同一个 inner block 中不要

34、声明相同的变量名称 在一个 statement 中避免将多个变量赋同一个值6.8.避免使用“魔术数字”这些数字很难与代码很好地配合。如以后需要修改它，无疑会成为一场噩梦，因为根本不知道“100”到底是指“数组大小”还是其他全然不同的东西。所以，应创建一个常数，并使用具有说服力的描述性名称，并在整个程序中都采用常数标识符。这样可使程序更易理解、更易维护。 6.9.byte 数组转换到 characters 为了将 byte 数组转换到 characters，你可以这么做： “Hello world!“.getBytes(); YINHAI SOFTWARE 撰写日期：2004 年 11 月 15

35、 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 26 页 共 29 页 撰写人：开发中心6.10. Utility 类 Utility 类（仅仅提供方法的类）应该被申明为抽象的来防止被继承或被初始化。 6.11. 初始化下面的代码是一种很好的初始化数组的方法： objectArguments = new Object arguments ; 6.12. 枚举类型 JAVA 对枚举的支持不好，但是下面的代码是一种很有用的模板： public class Colour public static final Colour BLACK = new Colour(0, 0,

36、 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 等可以象其他语言的枚举类型一样使用的常量。 他们可以用 =操作

37、符来比较。但是这样使用有一个缺陷：如果一个用户用这样的方法来创建颜色 BLACK new Colour(0， 0， 0) 那么这就是另外一个对象， =操作符就会产生错误，她的 equal() 方法仍然有效。我们可以将它的构造方法作用域限定为 private 来杜绝此情况。6.13. Swing 避免使用 AWT 组件混合使用 AWT 和 Swing 组件 如果要将 AWT 组件和 Swing 组件混合起来使用的话，请小心使用。实际上，尽量不要将他们混合起来使用。 滚动的 AWT 组件 AWT 组件绝对不要用 JscrollPane 类来实现滚动。滚动 AWT 组件的时候一定YINHAI SOF

38、TWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 27 页 共 29 页 撰写人：开发中心要用 AWT ScrollPane 组件来实现。 避免在 InternalFrame 组件中使用 AWT 组件 尽量不要这么做，要不然会出现不可预料的后果。 Z-Order 问题 AWT 组件总是显示在 Swing 组件之上。当使用包含 AWT 组件的 POP-UP 菜单的时候要小心，尽量不要这样使用。 6.14. 性能在写代码的时候，从头至尾都应该考虑性能问题。这不是说时间都应该浪费在优化代码上，而是我们时刻应该提醒自己要注意代

39、码的效率。比如：如果没有时间来实现一个高效的算法，那么我们应该在文档中记录下来，以便在以后有空的时候再来实现她。不是所有的人都同意在写代码的时候应该优化性能这个观点的，他们认为性能优化的问题应该在项目的后期再去考虑，也就是在程序的轮廓已经实现了以后。6.15. 使用 StringBuffer 对象 在处理 String 的时候要尽量使用 StringBuffer 类，StringBuffer 类是构成 String 类的基础。String 类将 StringBuffer 类封装了起来， （以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用 StringB

40、uffer 来实现大部分的工作，当工作完成后将 StringBuffer 对象再转换为需要的 String 对象。比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用 StringBuffer 对象和她的 append() 方法。如果我们用 String 对象代替 StringBuffer 对象的话，会花费许多不必要的创建和释放对象的 CPU 时间。 6.16. 避免太多的使用 synchronized 关键字 避免不必要的使用关键字 synchronized，应该在必要的时候再使用她，这是一个避免死锁的好方法。 Jbulider 不喜欢 synchronized 这

41、个关键字，如果你的断点设在这些关键字的作用域内的话，调试的时候你会发现断点会到处乱跳，让你不知所措。除非必须，尽量不要使用。 YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 28 页 共 29 页 撰写人：开发中心6.17. 换行如果需要换行的话，尽量用 println 来代替在字符串中使用“n ”。 不要这样： System.out.print(“Hello， world!n“); 要这样： System.out.println(“Hello， world!“); 或者构造一个带换行符的字符串，

42、至少要象这样： String newline = System.getProperty(“line.separator“); System.out.println(“Hello world“ + newline); 6.18. PrintStreamPrintStream 已经被不赞成（deprecated）使用，用 PrintWrite 来代替她。6.19. 数值计算在数值计算时要注意浮点误差，建议对数值类采用 BigDecimal。6.20. finalize()若在初始化过程中需要覆盖（取消）finalize() ，请记住调用 super.finalize()（若 Object属于我们的

43、直接超类，则无此必要） 。在对 finalize()进行覆盖的过程中，对 super.finalize()的调用应属于最后一个行动，而不应是第一个行动，这样可确保在需要基础类组件的时候它们依然有效。 6.21. 对象集合创建大小固定的对象集合时，请将它们传输至一个数组（若准备从一个方法里返回这个集合，更应如此操作） 。这样一来，我们就可享受到数组在编译期进行类型检查的好处。此外，为使用它们，数组的接收者也许并不需要将对象“造型”到数组里。 YINHAI SOFTWARE 撰写日期：2004 年 11 月 15 日银 海 软 件 Java 编程规范2018 年 09 月 11 日 第 29 页 共 29 页 撰写人：开发中心6.22. constructo