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

1、Java编码书写规范完整版Java编码书写规范版本修订记录序号简要说明（变更内容和变更范围）日期变更人3文档评审记录序号评审人角色评审日期签字评审意见目 录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. 类方法 （类的普通成员函数） 93.

2、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. 小括号（） 154.10. 运算符 154.11. 参数间隔 154.12. JSP文件命名 164.13. Servlet类命名（

3、待定） 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. 异常使用原则 191. 命名约定除了以下几个特例之外，命名时必须始终采用完整的英文描述符。此外，一般应采用小写字母，但类名、接口名以及任何非初始单词的第一个字母要大写。1.1. 一般概念 尽量使用完整的英文描述符 采用适用于相关领域的术语 采用大小写混合使名字可读 尽量少用缩写，但如果用

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

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

6、。 firstNamelastName实参/参数 同字段/属性的命名规则 public void setFirstName(String firstName) this.firstName = firstName;局部变量 同字段/属性的命名规则获取成员函数 被访问字段名的前面加上前缀 get。 getFirstName()getLastName()布尔型的获取成员函数 所有的布尔型获取函数必须用单词 is 做前缀。isPersistent()isString()设置成员函数 被访问字段名的前面加上前缀 set。 setFirstName()setLastName()setWarpSpeed(

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

8、uffer;StringBuffer sbContent;2. 注释约定2.1. 一般概念 注释应该增加代码的清晰度 保持注释的简洁 在写代码之前写注释 注释出为什么做了一些事，而不仅仅是做了什么2.2. 示范文档注释 在紧靠接口、类、成员函数和字段声明的前面注释它们。 /* 客户：客户是我们将服务和产品卖给的人或机构。*/String customer;C 语言风格注释 采用 C 语言风格的注释去掉不再使用但你仍想保留的代码。仍想保留是因为用户万一会改变想法，或者在调试过程中想让它暂时失效。 /* 这部分代码因为已被它之前的代码取代，由 B.Gustafsson, * 于 1999 年 6

9、月 4 日注释掉。如果两年之后还未使用，将 * 其删除。. . . * （源代码） */单行注释 在成员函数内采用单行注释，来说明业务逻辑、代码段和暂时变量的声明。注释符/后必须紧跟一个空格，然后才是注释信息。 / 遵照 Sarek 的规定，给所有/ 超过 $1000 的发货单/ 打 5% 的折扣。让利活/ 动于 1995年 2 月开始.if (condition) /* 处理条件 */ . 即约定主要的说明性注释使用文档注释；C风格注释只用来标注过期不用的代码；单行注释用来标注一些简单却容易混淆的逻辑，比较长的单独作为一行，较简洁的可以放在代码行尾。2.3. 注释范围类：类的目的、即类所完成

10、的功能，注释出采用的变量。接口：注释描述设置接口的目的、它应如何被使用。成员函数：对于设置与获取成员函数，在成员变量已有说明的情况下，可以不加注释；普通成员函数注释要求说明完成什么功能，参数含义及返回什么； 普通成员函数内部控制结构：注释代码做了些什么以及为什么这样做，处理顺序等。实参/参数：注释参数含义、及其它任何约束或前提条件字段/属性：注释字段的描述局部变量：无特别意义的情况下不加注释3. 文件样式约定3.1. Java(*.java)所有的 Java(*.java) 文件都必须遵守如下的样式规则：3.1.1. 版权信息版权信息必须在 java 文件的开头，比如： /* * Copyri

11、ght 2009 Wat Soft Co. Ltd. * All right reserved.* Author * Date 2009-02-27 */作者名称要用中文。其他不需要出现在 javadoc 的信息也可以包含在这里。3.1.2. Package/Importspackage 行要在 import 行之前，import 中标准的包名要在本地的包名之前，而且按照字母顺序排列。如果 import 行中包含了同一个包中的不同子目录，则应该用 * 来处理。package .stats;import java.io.*;import java.util.Observable;import h

12、otlava.util.Application;这里 java.io.* 是用来代替InputStream and OutputStream 的。3.1.3. Class类的注释 /* * Title: 文件名称 * Description: 类内容的简介 * 更新记录： * 格式:更新日期修改的版本操作人内容 * 2005-06-281.0张三完善create方法。 * * Copyright: Copyright (c) 2009 * Company: Wat Soft Co. Ltd. * version: 1.1 */类定义：包含了在不同行的 extends 和 implements

13、public class CounterSet extends Observable implements Cloneable3.1.4. Class Fields类的成员变量：/* * Packet counters */protected int packets;public 的成员变量必须生成文档（JavaDoc）。proceted、private和 package 定义的成员变量如果名字含义明确的话，可以没有注释。类变量的存取：如类的成员变量已经有注释，类变量的存取方法可以没有注释。public int getPackets() return this.packets; public

14、void setPackets(int packets) this.packets = packets; 3.1.5. 构造函数 构造函数：应该用递增的方式写（比如：参数多的写在后面）。 public CounterSet() this.size = 100;public CounterSet(int size) this.size = size;3.1.6. 克隆方法如果这个类是可以被克隆的，那么下一步就是 clone 方法： public Object clone() try catch(CloneNotSupportedException e) 3.1.7. 类方法 （类的普通成员函数）

15、类的方法：/* * Set the packet counters * param r1 - * param r2 - * */protected final void setArray(int r1, int r2, int r3, int r4) throws IllegalArgumentException / Ensure the arrays are of equal size 3.1.8. toString 方法 一般情况下，每一个类都应该定义 toString 方法： public String toString() 3.1.9. main 方法普通类，考虑置入一个main()方

16、法，其中包含用于测试那个类的代码，如果包含了main() 方法, 那么它应该写在类的底部。3.2. Java Server Page(*.jsp)所有的 Jsp(*.jsp) 文件都必须遵守如下的样式规则：3.2.1. 版本信息文件开头应有一个文件的版本注释，格式为3.2.2. tag关键tag的书写顺序为注意事项 使用国标扩展字符集(GBK)作为content的charset contentType在被包含的文件一定不能写，而其他文件一定要写 建议用以下两种格式： tag一律用小写，属性的值用双引号引起来。 出错信息定向到公用的出错页面 JSP页面与java编码要完全分离（待补充）。3.2.

17、3. 值输出输出值时使用。3.2.4. 嵌入代码段使用单独行“”结尾，注释参见2，代码块缩进参见4.2。% for(int i = 0; i 4. 其它代码书写风格约定4.1. 文档自动生成必须用 javadoc 来为类生成文档。不仅因为它是标准，这也是被各种 java 编译器都认可的方法。使用 author 标记是不被推荐的，因为代码不应该是被个人拥有的。4.2. 缩进缩进是必须的，并且在同一系统所有编码的缩进风格必须是统一的。4.3. 页宽页宽应该设置为80字符， 源代码不能超过此宽度。在任何情况下， 超长的语句应该在一个逗号或者一个操作符后折行。 一条语句折行后， 应该比原来的语句再缩进

18、3个字符。当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之： 在一个逗号后面断开 在一个操作符前面断开 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开 新的一行应该与上一行同一级别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进 8个空格。 以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /参

19、考 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /避免以下是两个缩进方法声明的例子。前者是常规情形。后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代之以缩进8个空格 / 常规缩进 someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /制表符缩进 private static synchronized horkingLongMethodName(in

20、t anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if语句的换行通常使用8个空格的规则，因为常规缩进(4个空格)会使语句体看起来比较费劲。比如： /不要用这种方式 if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); /用这种方式 if (condition1 & condition2) | (condition3 & conditio

21、n4) |!(condition5 & condition6) doSomethingAboutIt(); / 或者这种方式 if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 这里有三种可行的方法用于处理三元运算表达式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (

22、aLongBooleanExpression) ? beta : gamma; 4.4. 变量声明必须一行一个声明，因为这样以利于写注释。亦即， int level; / 标识层级别 int size; / 表大小要优于， int level, size; 4.5. 变量初始化尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。4.6. 局部变量声明只在代码块的开始处声明变量。（一个块是指任何被包含在大括号和中间的代码。）不要在首次用到该变量时才声明之。4.7. 空行空行将逻辑相关的代码段分隔开，以提高可读性。 下列情况应该总是使用两个空行： 一个源文件的

23、两个片段(section)之间 类声明和接口声明之间 下列情况应该总是使用一个空行： 两个方法之间 方法内的局部变量和方法的第一条语句之间 一个方法内的两个逻辑段之间，用以提高可读性 4.8. 大括号 中的语句应该单独作为一行。 例如：if (i0) i +; 4.9. 小括号（）左括号和后一个字符之间不应该出现空格； 同样， 右括号和前一个字符之间也不应该出现空格。 例如： CallProc( AParameter ); / 不符合规范 CallProc(AParameter); / 符合规范 不要在语句中使用无意义的括号，括号只应该为达到某种目的而出现在源代码中。4.10. 运算符每个运算

24、符与两边的字符之间都应该有一个空格。int num = 100; / 符合规范num += 1; / 符合规范num = num-1; / 不符合规范，应该是num = num - 1;4.11. 参数间隔多个参数之间的“，”应紧跟前面的参数，与后面的参数之间有一个空格。public int max(int a, int b, int c) / 符合规范 return Math.max(Math.max(a ,b),c); / 不符合规范，a后面应该由空格， / b和c的前面也应该由空格4.12. JSP文件命名采用完整的英文描述说明JSP所完成的功能，尽可能包括一个动词，第一个字母小写，如：

25、viewMessage.jsp、editUser.jsp或者forumChooser.jsp等。4.13. Servlet类命名（待定）一般对应于所服务的对象加后缀Service来命名，如：UserService，TradeService等。5. 编码指南 5.1. 对实例以及类变量的访问控制 若没有足够理由，不要把实例或类变量声明为公有。所有类成员变量要通过方法访问。通常，实例变量无需显式的设置(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;位于for循环中作为计数器值的数字常量，除了-1,0和1之外，不应被直接写入代码。 例如：for(int i=0;isize;i+) 5.4. 变量赋值 在一个语句中不允许给多个变量赋相同的值。它很难读懂。例如： fooBar.fChar = barFoo.lchar = c