Java编码规范v10.docx

1、Java编码规范v10Java编码规范（Java Coding Standard）V1.0 2011/9/16修改履历Ver修改时间修改的图表和章节编号状态修改概要说明修改人1.02011/9/16N向涛注：状态中，N是新建，A是追加，M是修改，D是删除。目 录目的 4范围 4前提条件 51 代码风格 51.1 一般格式说明 51.2 基本结构 52 代码结构 62.1 变更历史记录 62.2 Package声明 82.3 Import声明 92.4 Class Header 102.5 Class 112.6 常量（Menifest Variables） 132.7 成员变量（Instanc

2、e Variables） 142.8 初始块（Initializer Blocks） 142.9 构造器（Constructors） 152.10 属性（Properties） 162.11 方法（Methods） 172.12 内部类（Inner Class） 213 例子 22编码规范 231 命名规范 231.1 Package命名规范 231.2 Class命名规范 231.3 Method命名规范 251.4 变量命名规范 272 代码风格规范 292.1 控制语句风格规范 292.2 命令语句风格规范 312.3 声明语句风格规范 343 书写格式规范 364 设计规范 394.1

3、 质量测定基准（Metrics）规范 394.2 Class设计规范 394.3 Method设计规范 414.4 变量设计规范 425 Java语言规范 445.1 Object整体规范 445.2 修饰符规范 465.3 Javadoc规范 485.4 Import规范 495.5 字符串规范 495.6 数值规范 525.7 日期规范 525.8 集合规范 525.9 Stream规范 535.10 例外规范 545.11 线程规范 555.12 Servlet规范 585.13 EJB规范 60附录1 INDEX 621BD 622SD 623DD 624PG 625PT 646IT

4、64目的本文是博微广成研发部的规范文件。 本文的目的是统一Java的编码风格、提高代码质量。范围本文的适用范围是项目的编码阶段，同时也适用于项目的设计阶段和测试阶段。本文的适用项目是使用Java语言开发的项目。本文适用于掌握Java语言开发的开发人员。前提条件本文的第一条规则是任何规则都有例外。 如果在编码中有违反本文规则的地方，请加上注释。本文中的一些约定对您现在的编码习惯可能并没有绝对的好处，它们仅仅为了统一代码风格。Java编码规范概要Java代码风格概要说明如下。1 代码风格1.1 一般格式说明 除字符串和注释内以外， 代码中的空格一律为半角。 代码中不应有TAB字符（除字符串内），

5、需要TAB字符的地方一律替换成4个空格。 代码中换行和DOS系统相同，为/r/n。 代码应该有缩进， 缩进为4个空格。 缺省的一行代码最大长度为80个半角字符， 如果超过这个长度就需要换行。一般的情况下，换行后应缩进四格。 任何可以省略大括号的地方都不应省略大括号。1.2 基本结构一个类/接口的基本结构应该是这样的。初始Block（Initializer Blocks）以下依次说明。2 代码结构2.1 变更历史记录范例/* * MyClass.java * * 功 能： （一句话描述类的功能） * 类名： MyClass * * ver 更新日 责任人 更新内容 * * V1.00 2011-

6、01-01 程序猿 初版 * V1.01 2011-03-20 程序猿 修改* V1.10 2011-06-04 程序媛 修改* * Copyright (c) GCTEC All Rights Reserved.* LICENSE INFORMATION*/说明 “文件”的第一行是正文，在它前面没有NULL行。 需要修改的部分已经用粗体标出。 在“变更历史记录”中有一部分是版本编号（ver），具体的编号方法依从项目制定的版本变更策略。 在“变更历史记录”的版权信息中，有关于版权所有者的描述。其中的“GCTEC”，还未最后确定名称。 如果项目中有相关的许可信息（license），这些信息可以在

7、“LINCENSE INFORMATION”处加入。 如果项目中，变更履历使用CVS、SVN等源码管理系统维护，那么此 “变更历史记录” 可以精简为 /* $Header : /xxx/xxx/xxx.java $* $Revision : 1.4.1 $* $Date : 2011/09/16 02:23:08 $* * Copyright (c) gctec All Rights Reserved.* LICENSE INFORMATION*/2.2 Package声明范例 package com.gctec.myapp.mypack;说明 package遵循以下命名规则：1. packa

8、ge名全部为小写字母，中间用“.”分割。2. package名中禁止使用除小写英语句半角字母以外的任何字符，但是根据需要可以使用下划线“_”。 例如 package com.gctec.my_app.mypack;3. 标准的package名可以分为三部分：.。其中“公司名”部分可以是“公司名称 + 部门名称”。例如 package com.gctect.dev.myapp.mypack;根据需要“公司名”部分也可省略。其中“应用程序名”部分可以是“应用程序名称 + 子程序名称”。例如 package com.gctec.myapp.subapp.mypack;一般来说，“应用程序名”部分不能

9、省略。其中“包名”部分应该根据程序设计的包结构来定义；“包名”这部分可以根据需要省略。 通常，“Package声明”部分不能省略。 如果是应用程序比较简单，可以简化package的名称。例如，简单的试验使用的类，可以命名为“myapp.test”或者“test”；如果是一个小程序，可以命名为“myapp”或者“main”。2.3 Import声明范例 import java.util.HashMap;import java.util.Map;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpSe

10、rvletResponse;import org.apache.log4j.Appender;import org.apache.log4j.Category;import com.gctec.myapp.thatpack;説明 “Import声明”内部没有NULL行。 “Import声明”的次序是java.* - javax.* - 中间件、库等提供的package - 程序中的package Import需要指出import哪一个类，禁止import整个package。 例如 import java.util.*; /错误import java.util.HashMap; /正确 通常程序

11、内部用到的package都是用import语句声明在程序头部；原则上，程序内部不再出现没有import声明的类。 例如 java.io.File file = new java.io.File(“test.txt”); /错误File file = new File(“test.txt”); /正确但是会混淆的声明应该在程序中特别指出是那一个package中的。例如： import java.util.Date;import java.sql.Date;java.util.Date date = new java.util.Date(); 程序中用到的类应该在Import中声明，但是程序中没有

12、用到的类不要出现在Import中。 例如 import java.util.HashMap; - 删除（程序中未使用HashMap这样的类）2.4 Class Header范例/* * (这里用一句话描述这是一个什么样的类，格式：本类是XXXXXX。) * (这里用15句话描述这个类的功能是什么。 - 可选)* (这里介绍这个类涉及到的相关信息。 譬如，专有名词、概念的简单解释。 - 可选)* (这里介绍这个类在系统中的角色， 以及如何和其他类交互。 - 可选)* (这里介绍这个类的WHY，即为什么会存在这样一个类。 - 可选)* (这里介绍这个类的使用方法。 - 可选)* (这里是使用这个类

13、的sample。 - 可选)* (这里是使用这个类的注意事项。 - 可选) * * author 程序猿 * version Ver 1.2 2011-09-16 修订 * since CodingExample Ver 1.1 * * see YourClass, HisClass* deprecated （这里写deprecated的信息） */说明 “Class Header”可以分为3部分说明部分、版本信息和其他信息，中间使用NULL行分割。 程序中的每一个类都必须有Class注释。根据需要，Class注释中除了说明部分不能省略外，版本信息和其他信息都可以省略。 Class注释中的说明

14、部分的写法参考范例，根据需要，可以省略其中的一些说明部分（可省略的部分后标有可选）。 Class注释的版本信息中，除since可以根据需要省略外，其他的都不可省略。 Class注释的版本信息要上下对齐。对齐 * author 程序猿 * version Ver 1.2 2011-09-16 修订 * since CodingExample Ver 1.1 version信息的结构是 “Ver ”。 其中“版本”是项目版本，具体依据项目制定的版本变更规范；其中“日期”为此文件最后一次修改的日期；其中状态有两种选择“新建”和“修订”。 since信息的结构是“ Ver ”。 其中“项目名称”可以是

15、项目的全称也可以是项目的简称，但是要注意在整个项目中这个名称应该不变； 其中“版本”是表示这个类从哪个版本开始存在。 Class注释的其他信息中，see和deprecated都可以省略。 deprecated的说明信息的结构是“ ”。例如 * deprecated CodingExample 1.2中，不推荐此Class。此Class的功能，被替换为com.gctec.myapp.AnotherClass Class了。* deprecated CodingExample 1.2中，不推荐此Class。没有替补。根据需要，选择上面两种表述方法中的一种，替换划线部分，做成需要的deprecate

16、d信息。2.5 Class范例 public class MyClass extends SuperClass throws Exception /do sth. (Class Body)说明 Class Body应该缩进4格。 Class声明部分可以分为4部分Class前缀、Class名、扩展信息和例外信息。 Class声明的结构是“public/protected/private final/abstract/static/strictfp class/interface extends implements throws ”。4. 关于public/protected/private，在

17、一般情况下（指Top-Level Class）， 规定所有的类都应该显式声明为public。5. 关于final，如果项目中没有显式地强调安全性，规定禁止将一个类声明为final。6. 关于abstract， 如果一个类可以声明成interface，规定禁止把类声明为abstract；如果一个类中没有abstract的方法，规定禁止把类声明为abstract。7. 不能继承声明为static的类。8. 如果项目中不涉及到严格的数据运算（譬如，强调float和double的运算），那么禁止把类声明为strictfp。 Class的命名遵循以下规则。9. Class的名称应该是一个名词短语。 可以

18、是“形容词/名词 + 名词”的形式。 例如InputDataStream、Developer、OrderItem等。10. Class的名称由1个或1个以上的英语句单词组成， 其中每一个英语句单词的首字母应该大写， 其余字母小写。11. 规定Class名称只能由26个英文字母组成。12. Class命名应该具有一致性。 （一致性是指，如果在设计阶段确定了一个实体， 那么和这个实体相关的Class应该具有一致的名称。 举例来说，“用户”这个实体可以被称作User、Account或者Person。 如果决定使用User来表示这个实体的话， 则相应的Class名应该是UserFile和UserFil

19、eParser等， 避免在系统中出现既有UserFile又有AccountFileParser的情况。）13. 表示复数的Class可以命名为“单数+s”的形式。 例如，User和Users、Action和Actions、Mapping和Mappings等。14. Interface的名称可以是一个名词或者是一个形容词。 例如IService和IRunnable。15. 规定Interface名称只能由26个英文字母组成。16. Interface的名称由1个或1个以上的英语句单词组成， 其中每一个英语句单词的首字母应该大写， 其余字母小写；规定Interface的名称前应该有一个“I”。17

20、. 实现Interface的类一般地应该加上后缀“Imp”。 例如，接口IListener对应MyListenerImp。 关于Class声明部分的缩进， 可以在如下形式中选择一种。 public class MyClass extends YourClass implements TheirClass throws OurException public class MyClass extends YourClass throws OurException, TheirException, AnotherException public class MyClass extends YourC

21、lass implements whichIF, whatIF, whereIFpublic class MyClass extends YourClass implements whichIF, whatIF, whereIF throws OurException, TheirException, AnotherException2.6 常量（Menifest Variables）范例 /* * （用一句话描述这个变量表示什么）* since CodingExample Ver 1.1 */public static final int MAX_LENTH = 25;public stat

22、ic final int Max_Lenth = 25;说明 类中常量的声明位于类的最前面， 和类的声明之间NULL一行。 在声明常量的时候给它付值。 规定常量应该被修饰为public、static和final；一般地，把public改成protected和private没有特别大的意义。 常量的名称使用26个英语句大写字母和下划线“_”组成。 或者首字母大写和下划线“_”组成。 如无设计上的必要，规定把常量写在class中代替把常量写在interface中。2.7 成员变量（Instance Variables）范例 /* * （用一句话描述这个变量表示什么） * * since Codin

23、gExample Ver 1.0 */ private String name = null;说明 在声明变量时应该给它付值。却省对象付值为null；整型、长型、浮点型等为0；布尔型为false。 一般地，类成员变量声明为private。如果需要访问，则提供相应的getter和setter方法。 原则上不通过instance._variable的方式访问。如果设计上无继承扩展的考虑，则不应声明为protected。规定类成员变量不声明为friendly。 类成员变量的名称使用26个英文字母开头。 类成员变量是否为static应该在设计时决定。一般地，不要把类成员变量声明为final（即，如果声

24、明为final，那么必须声明static，作为常量使用）。2.8 初始块（Initializer Blocks）范例 /* * （这里描述这部分代码的作用） * * since CodingExample Ver 1.0 */ static /本体处理 说明 是否使用static block应该在设计时决定。 原则上，在声明类成员变量的时候同时进行初始化。 如非必要，不应把声明时的初始化工作在static block中做。例如 private String _name;static name = “Default Name”;/错误private String name = “Default

25、Name”; /正确2.9 构造器（Constructors）范例 /* * （这里描述这个构造器的作用） * * since CodingExample Ver 1.0 */ public MyClass() /本体处理 说明 缺省的构造器必须显示的声明。 如无设计上的要求，构造器一律声明为public；对于Singelton模式，构造器可以声明为private；在不是必要的条件下，不应把构造器声明为protected和friendly。 如果缺省构造器中没有任何代码，则应使用“/null”标注。 public MyClass() /错误 public MyClass() /正确 /null

26、 2.10 属性（Properties）范例 /* * 获取名称。 * * return String 名称 * since CodingExample Ver 1.0 */ public String getName() return name; /* * 设置名称。 * * param name 名称 * since CodingExample Ver 1.0 */ public void setName(String name) this.name = name; 说明 请在类中做getter方法、setter方法，方法的命名遵循JavaBean属性的命名规范。 getter方法使用“g

27、et + 属性名”；setter方法使用“set + 属性名”；对于返回boolean的getter，使用“is + 属性名”。 与属性对应的类成员变量的名字同属性名相同。 例如，上例中，属性“name”对应的类成员变量是“name”。 属性名使用26个英文字母组成。 属性的getter和setter方法应该为public。 使用一些编辑器如eclipse时，推荐自动生成getter和setter。2.11 方法（Methods）范例 /* * (这里用一句话描述这个方法的作用) * (这里描述这个方法适用条件 可选) * (这里描述这个方法的执行流程 可选) * (这里描述这个方法的使用方法

28、 可选) * (这里描述这个方法的注意事项 可选) * * param file 设定文件 * return Document DOM对象 * throws IOException设定文件中缺少信息时 * since CodingExampleVer 1.1 */ public Document parse(File file) throws IOException / 1. 取得处理要求的所有数据/检查数据的有效性 / 2. 处理本体 / 3. 返回/保存结果说明 方法部分中，每个方法之间有一NULL行。 一个方法的注释中，包含这个方法的说明、参数说明、返回值说明、例外说明和since（或d

29、eceprated）。规定，这几个部分在方法中存在的情况下，必须给出相应的说明。例如，如果方法有返回值，则必须给出return的说明。 如果方法的参数和返回值有特殊要求，一定要在注释中写明。 例如， * param file 设定文件，NULL也可 * return Map Action Mapping、key-String、value-String 关于方法的since和deceprated参见Class Header部分。 关于参数说明、返回值说明等的对齐，参见Class Header部分。 关于方法声明的缩进，参见Class部分。 一个方法声明为public/protected/private应该在设计时决定。原则上，如果没有声明为