Java编码书写规范完整版.doc

1、Java 编码书写规范版本修订记录序号 简要说明（变更内容和变更范围） 日期 变更人3文档评审记录序号 评审人 角色 评审日期 签字 评审意见Java 编码书写规范 文档编号：目 录1. 命名约定 11.1. 一般概念 11.2. 示范 12. 注释约定 42.1. 一般概念 42.2. 示范 42.3. 注释范围 53. 文件样式约定 53.1. JAVA(*.JAVA) 53.1.1. 版权信息 63.1.2. PACKAGE/IMPORTS 63.1.3. CLASS 63.1.4. CLASS FIELDS 73.1.5. 构造函数 83.1.6. 克隆方法 83.1.7. 类方法 （

2、类的普通成员函数） 93.1.8. TOSTRING 方法 93.1.9. MAIN 方法 93.2. JAVA SERVER PAGE(*.JSP) 93.2.1. 版本信息 103.2.2. TAG 103.2.3. 值输出 113.2.4. 嵌入代码段 114. 其它代码书写风格约定 114.1. 文档自动生成 114.2. 缩进 124.3. 页宽 124.4. 变量声明 144.5. 变量初始化 144.6. 局部变量声明 144.7. 空行 144.8. 大括号 154.9. 小括号（） 15Java 编码书写规范 文档编号：4.10. 运算符 154.11. 参数间隔 154.1

3、2. JSP 文件命名 164.13. SERVLET 类命名（待定） 165. 编码指南 165.1. 对实例以及类变量的访问控制 165.2. 引用类变量和类方法 165.3. 常量 175.4. 变量赋值 175.5. 其它惯例 185.5.1. 圆括号 185.5.2. 返回值 185.5.3. 条件运算符“?“前的表达式 195.5.4. 特殊注释 195.5.5. 异常使用原则 19Java 编码书写规范 文档编号：1. 命名约定除了以下几个特例之外，命名时必须始终采用完整的英文描述符。此外，一般应采用小写字母，但类名、接口名以及任何非初始单词的第一个字母要大写。1.1.一般概念

4、尽量使用完整的英文描述符 采用适用于相关领域的术语 采用大小写混合使名字可读 尽量少用缩写，但如果用了，要明智地使用，且在整个工程中统一 避免使用长的名字（尽量小于 25 个字母） 避免使用类似的名字，或者仅仅是大小写不同的名字 避免使用下划线（除静态常量等）1.2.示范包（Package） 采用完整的英文描述符，应该都是由小写字母组成，格式为com.dcosft.*。如：monscom.dcsoft.utility类（Class ） 采用完整的英文描述符，所有单词的第一个字母大写，在上下文语境允许的情况下，可以使用缩略词，但必须保证整个开发小组的一致性，比如：number 可缩写为 num。

5、 如：接口（Interface） 采用完整的英文描述符说明接口封装，所有单词的第一个字母大CustomerSavingsAccountJava 编码书写规范 文档编号：写。在接口名称的最前面使用大写的“I”表明这是一个接口。习惯上，名字后面加上后缀 able， ible 或者 er，但这不是必需的。 如：组件/部件（Component） 使用完整的英文描述来说明组件的用途，前端加上组件类型。 如：异常（Exception） 采用异常类型的各单词首字母表示异常。 如：字段/属性 字段采用完整的英文描述，第一个字母小写，任何中间单词的首字母大写。 实参/参数 同字段/属性的命名规则 局部变量 同字

6、段/属性的命名规则获取成员函数 被访问字段名的前面加上前缀 get。 IContactableIPrompterbtnOKlstCustomermenuFileExcpetion eIOException ioefirstNamelastNamepublic void setFirstName(String firstName) this.firstName = firstName;getFirstName()getLastName()Java 编码书写规范 文档编号：布尔型的获取成员函数 所有的布尔型获取函数必须用单词 is 做前缀。设置成员函数 被访问字段名的前面加上前缀 set。 普通成

7、员函数 采用完整的英文描述说明成员函数功能，第一个单词尽可能采用一个动词，第一个字母小写。 静态常量字段（static final） 全部采用大写字母，单词之间用下划线分隔。 循环计数器 通常采用字母 i，j，k，m，n 或者 counter 都可以接受。 数组应该总是用下面的方式来命名：objectType variant，不得使用 objectType variant方式。对象实例 同组件/部件isPersistent()isString()setFirstName()setLastName()setWarpSpeed()openFile()addAccount()MIN_BALANCE,

8、DEFAULT_DATEi, j, km,n,counterint arrInt;String args;byte arrBuffer;StringBuffer sbContent;Java 编码书写规范 文档编号：2. 注释约定2.1.一般概念 注释应该增加代码的清晰度 保持注释的简洁 在写代码之前写注释 注释出为什么做了一些事，而不仅仅是做了什么2.2.示范文档注释 在紧靠接口、类、成员函数和字段声明的前面注释它们。 C 语言风格注释 采用 C 语言风格的注释去掉不再使用但你仍想保留的代码。仍想保留是因为用户万一会改变想法，或者在调试过程中想让它暂时失效。 单行注释 在成员函数内采用单行注

9、释，来说明业务逻辑、代码段和暂时变量的声明。注释符“/“后必须紧跟一个空格，然后才是注释信息。 /* 客户：客户是我们将服务和产品卖给的人或机构。 */String customer;/* 这部分代码因为已被它之前的代码取代，由 B.Gustafsson,* 于 1999 年 6 月 4 日注释掉。如果两年之后还未使用，将* 其删除。 . . .* （源代码）*/ 遵照 Sarek 的规定，给所有/ 超过 $1000 的发货单/ 打 5% 的折扣。让利活/ 动于 1995 年 2 月开始 .if (condition) /* 处理条件 */ . Java 编码书写规范 文档编号：即约定主要的说

10、明性注释使用文档注释；C 风格注释只用来标注过期不用的代码；单行注释用来标注一些简单却容易混淆的逻辑，比较长的单独作为一行，较简洁的可以放在代码行尾。2.3.注释范围类：类的目的、即类所完成的功能，注释出采用的变量。接口：注释描述设置接口的目的、它应如何被使用。成员函数：对于设置与获取成员函数，在成员变量已有说明的情况下，可以不加注释；普通成员函数注释要求说明完成什么功能，参数含义及返回什么； 普通成员函数内部控制结构：注释代码做了些什么以及为什么这样做，处理顺序等。实参/参数：注释参数含义、及其它任何约束或前提条件字段/属性：注释字段的描述局部变量：无特别意义的情况下不加注释3. 文件样式约

11、定3.1.Java(*.java)所有的 Java(*.java) 文件都必须遵守如下的样式规则：3.1.1. 版权信息版权信息必须在 java 文件的开头，比如： /* Copyright 2009 Wat Soft Co. Ltd.* All right reserved.* Author * Date 2009-02-27*/Java 编码书写规范 文档编号：作者名称要用中文。其他不需要出现在 javadoc 的信息也可以包含在这里。3.1.2. Package/Importspackage 行要在 import 行之前，import 中标准的包名要在本地的包名之前，而且按照字母顺序排列

12、。如果 import 行中包含了同一个包中的不同子目录，则应该用 * 来处理。这里 java.io.* 是用来代替 InputStream and OutputStream 的。3.1.3. Class类的注释 package .stats;import java.io.*;import java.util.Observable;import hotlava.util.Application;/* Title: 文件名称 * Description: 类内容的简介 * 更新记录： * 格式 :更新日期 修改的版本 操作人 内容 * 2005-06-281.0张三 完善 create 方法。 *

13、 * Copyright: Copyright (c) 2009* Company: Wat Soft Co. Ltd.* version: 1.1*/Java 编码书写规范 文档编号：类定义：包含了在不同行的 extends 和 implements 3.1.4. Class Fields类的成员变量：public 的成员变量必须生成文档（JavaDoc） 。proceted、private 和 package 定义的成员变量如果名字含义明确的话，可以没有注释。类变量的存取：如类的成员变量已经有注释，类变量的存取方法可以没有注释。3.1.5. 构造函数 构造函数：应该用递增的方式写（比如：参

14、数多的写在后面） 。 public class CounterSetextends Observableimplements Cloneable/* Packet counters*/protected int packets;public int getPackets() return this.packets; public void setPackets(int packets) this.packets = packets; Java 编码书写规范 文档编号：3.1.6. 克隆方法如果这个类是可以被克隆的，那么下一步就是 clone 方法： 3.1.7. 类方法 （类的普通成员函数）类

15、的方法：public CounterSet()this.size = 100;public CounterSet(int size)this.size = size;public Object clone() try catch(CloneNotSupportedException e) /* Set the packet counters* param r1 - * param r2 - * */protected final void setArray(int r1, int r2, int r3, int r4)throws IllegalArgumentException/ Ensur

16、e the arrays are of equal size Java 编码书写规范 文档编号：3.1.8. toString 方法 一般情况下，每一个类都应该定义 toString 方法： 3.1.9. main 方法普通类，考虑置入一个 main()方法，其中包含用于测试那个类的代码，如果包含了main() 方法, 那么它应该写在类的底部。3.2.Java Server Page(*.jsp)所有的 Jsp(*.jsp) 文件都必须遵守如下的样式规则：3.2.1. 版本信息文件开头应有一个文件的版本注释，格式为public String toString() Java 编码书写规范 文档编

17、号：3.2.2. tag关键 tag 的书写顺序为注意事项 使用国标扩展字符集(GBK)作为 content 的 charset contentType 在被包含的文件一定不能写，而其他文件一定要写 建议用以下两种格式： tag 一律用小写，属性的值用双引号引起来。 出错信息定向到公用的出错页面 JSP 页面与 java 编码要完全分离（待补充） 。3.2.3. 值输出输出值时使用。3.2.4. 嵌入代码段使用单独行“ ”结尾，注释参见 2，代码块缩进参见 4.2。Java 编码书写规范 文档编号：4. 其它代码书写风格约定4.1.文档自动生成必须用 javadoc 来为类生成文档。不仅因为它

18、是标准，这也是被各种 java 编译器都认可的方法。使用 author 标记是不被推荐的，因为代码不应该是被个人拥有的。4.2.缩进缩进是必须的，并且在同一系统所有编码的缩进风格必须是统一的。4.3.页宽页宽应该设置为 80 字符， 源代码不能超过此宽度。在任何情况下， 超长的语句应该在一个逗号或者一个操作符后折行。 一条语句折行后， 应该比原来的语句再缩进 3个字符。当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之： 在一个逗号后面断开 在一个操作符前面断开 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开 新的一行应该与上一行同一级

19、别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进 8 个空格。 以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。 Java 编码书写规范 文档编号：longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /参考 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /避免以下是两个缩进方法声明的例子。前者是常

20、规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进 8 个空格 / 常规缩进someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /制表符缩进 private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if 语句的换行通常使用 8 个空格的规则，因为

21、常规缩进(4 个空格)会使语句体看起来比较费劲。比如： /不要用这种方式 if (condition1 /用这种方式 if (condition1 / 或者这种方式if (condition1 这里有三种可行的方法用于处理三元运算表达式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression)? beta : gamma; 4.4.变量声明必须一行一个声明，因为这样以利于写注释。亦即， in

22、t level; / 标识层级别int size; / 表大小要优于， int level, size; 4.5.变量初始化尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。Java 编码书写规范 文档编号：4.6.局部变量声明只在代码块的开始处声明变量。 （一个块是指任何被包含在大括号“和“中间的代码。 ）不要在首次用到该变量时才声明之。4.7.空行空行将逻辑相关的代码段分隔开，以提高可读性。 下列情况应该总是使用两个空行： 一个源文件的两个片段(section)之间 类声明和接口声明之间 下列情况应该总是使用一个空行： 两个方法之间 方法内的局部变量

23、和方法的第一条语句之间 一个方法内的两个逻辑段之间，用以提高可读性 4.8.大括号 中的语句应该单独作为一行。 例如：4.9.小括号（）左括号和后一个字符之间不应该出现空格； 同样， 右括号和前一个字符之间也不应该出现空格。 例如： 不要在语句中使用无意义的括号，括号只应该为达到某种目的而出现在源代码中。if (i0) i +; CallProc( AParameter ); / 不符合规范 CallProc(AParameter); / 符合规范 Java 编码书写规范 文档编号：4.10. 运算符每个运算符与两边的字符之间都应该有一个空格。4.11. 参数间隔多个参数之间的“， ”应紧跟前

24、面的参数，与后面的参数之间有一个空格。4.12. JSP 文件命名采用完整的英文描述说明 JSP 所完成的功能，尽可能包括一个动词，第一个字母小写，如：viewMessage.jsp 、editUser.jsp 或者 forumChooser.jsp 等。4.13. Servlet 类命名（待定）一般对应于所服务的对象加后缀 Service 来命名，如：UserService，TradeService 等。5. 编码指南 5.1. 对实例以及类变量的访问控制 若没有足够理由，不要把实例或类变量声明为公有。所有类成员变量要通过方法访int num = 100; / 符合规范num += 1; /

25、 符合规范num = num-1; / 不符合规范，应该是 num = num - 1;public int max(int a, int b, int c) / 符合规范return Math.max(Math.max(a ,b),c); / 不符合规范， a 后面应该由空格，/ b 和 c 的前面也应该由空格Java 编码书写规范 文档编号：问。通常，实例变量无需显式的设置(set)和获取(gotten)，通常这作为方法调用的边缘效应 (side effect)而产生。 一个具有公有实例变量的恰当例子，是类仅作为数据结构，没有行为。亦即，若你要使用一个结构(struct)而非一个类 (如果

26、 java 支持结构的话)，那么把类的实例变量声明为公有是合适的。 5.2.引用类变量和类方法 避免用一个对象访问一个类的静态变量和方法。应该用类名替代。例如： classMethod(); /正确AClass.classMethod(); /正确anObject.classMethod(); /避免! 5.3.常量 Java 中的常量值要用字符串表示,它区分为不同的类型,如整型常量 123,实型量1.23,字符常量 a ,布尔常量 true、 false 以及字符串常量“This is a constant string.“。 例如：final double PI=3.14159;位于 fo

27、r 循环中作为计数器值的数字常量，除了-1,0 和 1 之外，不应被直接写入代码。例如：for(int i=0;i= 0) ? x : -x; 5.5.4. 特殊注释 在注释中使用 XXX 来标识某些未实现(bogus)的但可以工作(works)的内容。用FIXME 来标识某些假的和错误的内容。 5.5.5. 异常使用原则 异常在 java 编码过程中，在使用过程中应该注意遵守以下原则： 首先，不要丢弃异常，即 catch 异常后什么也不做。如果你认为不能很好的处理该异常，就让它继续传播，让别的地方处理去；或者，你可以把一个低级的异常转换成应用级的异常，重新抛出。 catch 语句应该指定具体的异常类型。不要把不该捕获的异常也扣下了。 在 finally 里面释放资源。如果 finally 里面也会抛出异常，也一样的需要 try Java 编码书写规范 文档编号：catch 处理。 不要把大量的代码放在 try catch 块里面，分离各个可能出现异常的语句并分别捕获异常。 由于异常可能导致输出的数据不完整，应该作出相应处理，至少要应提示数据的不完整。