java编码规范

 

 

 

 

 

 

 

 

Java 编码规范
（ Java Coding Standard ）

 

 

 

目 录

 

Java编码规范概要 4

1代码风格 4

1.1一般格式说明 4

1.2基本结构 4

2代码结构 5

2.1变更履历 5

2.2Package声明 7

2.3Import声明 8

2.4Class Header 9

2.5Class 10

2.6常量（ Menifest Variables） 12

2.7成员变量（ Instance Variables） 13

2.8初始块（ Initializer Blocks） 13

2.9构造器（ Constructors） 14

2.10属性（ Properties） 15

2.11方法（ Methods） 15

2.12内部类（ Inner Class） 21

3例子 21

编码规范 24

1命名规范 24

1.1Package命名规范 24

1.2Class命名规范 25

1.3Method命名规范 27

1.4变量命名规范 29

2代码风格规范 31

2.1控制语句风格规范 31

2.2命令语句风格规范 33

2.3声明语句风格规范 35

3书写格式规范 38

4设计规范 41

4.1质量测定基准（ Metrics）规范 41

4.2Class设计规范 41

4.3Method设计规范 43

4.4变量设计规范 44

5Java语言规范 46

5.1Object整体规范 46

5.2修饰符规范 48

5.3Javadoc规范 50

5.4Import规范 51

5.5字符串规范 51

5.6数值规范 53

5.7日期规范 54

5.8集合规范 54

5.9Stream规范 55

5.10例外规范 56

5.11线程规范 57

5.12Servlet规范 59

5.13EJB规范 61

 

 

 

 

 

 

 

 

 

 

 

Java 编码规范概要

Java 代码风格概要说明如下。

1. 代码风格

   1. 一般格式说明

• 除字符串和注释内以外， 代码中的空格一律为半角。

• 代码中不应有 [TAB] 字符（除字符串内）， 需要 [TAB] 字符的地方一律替换成 4 个空格。

• 代码中换行和 DOS 系统相同，为 /r/n 。

• 代码应该有缩进， 缩进为 4 个空格。

• 缺省的一行代码最大长度为 80 个半角字符， 如果超过这个长度就需要换行。一般的情况下，换行后应缩进四格。

• 任何可以省略大括号的地方都不应省略大括号。

 

 

1.  

   1. 基本结构

一个类 / 接口的基本结构应该是这样的。

以下依次说明。

 

1. 代码结构

   1. 变更履历

范例

 

 

说明

 

• “文件”的第一行是正文，在它前面没有 NULL 行。

• 当客户要求代码规约的时候， 使用上述模版。 其中需要修改的部分已经用粗体 标出。

• 在“变更履历”中有一部分是版本编号（ ver ），具体的编号方法依从项目制定的版本变更策略。

• 在“变更履历”的版权信息中，有关于年份的描述。其中“ 2002” 是指这个类第一次发行的年份；“ 2003” 是指这个类最后一次发行的年份。

• 在“变更履历”的版权信息中，有关于版权所有者的描述。其中的“ Neusoft Business Software” ，根据不同的项目，可以修改成 TOSHIBA 等字样。

• 如果项目中有相关的许可信息（ license ），这些信息可以在“ LINCENSE INFORMATION” 处加入。

• 如果项目中，变更履历使用 CVS 等源码管理系统维护，那么此 “变更履历” 可以精简为

 

1.  

   1. Package 声明

范例

 

 

说明

 

• 在客户没有明确指定 package 的条件下， package 遵循以下命名规则：

  1. package 名全部为小写字母，中间用“ .” 分割。

  2. package 名中禁止使用除小写英语句半角字母以外的任何字符，但是根据需要可以使用下划线“ _” 。 例如

•  

  1. 标准的 package 名可以分为三部分： < 公司名 >.< 应用程序名 >.< 包名 > 。其中“公司名”部分可以是“公司名称 + 部门名称”。例如

根据需要“公司名”部分也可省略。其中“应用程序名”部分可以是“应用程序名称 + 子程序名称”。例如

一般来说，“应用程序名”部分不能省略。其中“包名”部分应该根据程序设计的包结构来定义；“包名”这部分可以根据需要省略。

• 通常，“ Package 声明”部分不能省略。 如果是应用程序比较简单，可以简化 package 的名称。例如，简单的试验使用的类，可以命名为“ myapp.test” 或者“ test” ；如果是一个小程序，可以命名为“ myapp” 或者“ main” 。

• 规定在每个 package 的目录下（前提是这个 package 中有 class 文件）， 都必须有一个 package.html 文件。 使用这个文件来描述这个 package 的信息。

 

1.  

   1. Import 声明

范例

 

 

説明

• “Import 声明”内部没有 NULL 行。

• “Import 声明”的次序是

java.* -> javax.* -> 中间件、库等提供的 package -> 程序中的 package

• Import 需要指出 import 哪一个类，禁止 import 整个 package 。 例如

• 通常程序内部用到的 package 都是用 import 语句声明在程序头部；原则上，程序内部不再出现没有 import 声明的类。 例如

但是会混淆的声明应该在程序中特别指出是那一个 package 中的。例如：

• 程序中用到的类应该在 Import 中声明，但是程序中没有用到的类不要出现在 Import 中。 例如

 

1.  

   1. Class Header

范例

 

 

说明

 

• “Class Header” 可以分为 3 部分——说明部分、版本信息和其他信息，中间使用 NULL 行分割。

• 程序中的每一个类都必须有 Class 注释。根据需要， Class 注释中除了说明部分不能省略外，版本信息和其他信息都可以省略。

• Class 注释中的说明部分的写法参考范例，根据需要，可以省略其中的一些说明部分（可省略的部分后标有可选）。

• Class 注释的版本信息中，除 @since 可以根据需要省略外，其他的都不可省略。

• Class 注释的版本信息要上下对齐。

• @version 信息的结构是 “ Ver < 版本 > < 日期 > < 状态 >” 。 其中“版本”是项目版本，具体依据项目制定的版本变更规范；其中“日期”为此文件最后一次修改的日期；其中状态有两种选择“新规做成”和“改订”。

• @since 信息的结构是“ < 项目名称 > Ver < 版本 >” 。 其中“项目名称”可以是项目的全称也可以是项目的简称，但是要注意在整个项目中这个名称应该不变； 其中“版本”是这个类第一次被创建时的项目版本，具体依据项目制定的版本变更规范。

• Class 注释的其他信息中， @see 和 @deprecated 都可以省略。

• @deprecated 的说明信息的结构是“ < 在哪个版本中不推荐使用 > < 使用哪个类替代 >” 。例如

根据需要，选择上面两种表述方法中的一种，替换划线部分，做成需要的 @deprecated 信息。

 

1.  

   1. Class

范例

 

 

说明

 

• Class Body 应该缩进 4 格。

• Class 的最后一行规定以“ } ///:~” 结尾。 这样做有以下好处。

  1. 标明到了文件最后一行。

  2. 防止不小心删除最后一个字符（大括号）。

  3. 有些编辑器可以去除每行后的空格，但是也有可能把这个大括号删除了。以这样结尾，可以防止这一点。

• Class 声明部分可以分为 4 部分—— Class 前缀、 Class 名、扩展信息和例外信息。

• Class 声明的结构是“ [public/protected/private] [final/abstract/static/strictfp] class/interface < 类名 > [extends …] [implements …] [throws …]” 。

  1. 关于 public/protected/private ，在一般情况下（指 Top-Level Class ）， 规定所有的类都应该显式声明为 public 。

  2. 关于 final ，如果项目中没有显式地强调安全性，规定禁止将一个类声明为 final 。

  3. 关于 abstract ， 如果一个类可以声明成 interface ，规定禁止把类声明为 abstract ；如果一个类中没有 abstract 的方法，规定禁止把类声明为 abstract 。

  4. 不能继承声明为 static 的类。

  5. 如果项目中不涉及到严格的数据运算（譬如，强调 float 和 double 的运算），那么禁止把类声明为 strictfp 。

• Class 的命名遵循以下规则。

  1. Class 的名称应该是一个名词短语。 可以是“形容词 / 名词 + 名词”的形式。 例如 InputDataStream 、 Developer 、 OrderItem 等。

  2. Class 的名称由 1 个或 1 个以上的英语句单词组成， 其中每一个英语句单词的首字母应该大写， 其余字母小写。

  3. 规定 Class 名称只能由 26 个英文字母组成。

  4. Class 命名应该具有一致性。 （一致性是指，如果在设计阶段确定了一个实体， 那么和这个实体相关的 Class 应该具有一致的名称。 举例来说，“用户”这个实体可以被称作 User 、 Account 或者 Person 。 如果决定使用 User 来表示这个实体的话， 则相应的 Class 名应该是 UserFile 和 UserFileParser 等， 避免在系统中出现既有 UserFile 又有 AccountFileParser 的情况。）

  5. 表示复数的 Class 可以命名为“单数 +s” 的形式。 例如， User 和 Users 、 Action 和 Actions 、 Mapping 和 Mappings 等。

  6. Interface 的名称可以是一个名词或者是一个形容词。 例如 IService 和 IRunnable 。

  7. 规定 Interface 名称只能由 26 个英文字母组成。

  8. Interface 的名称由 1 个或 1 个以上的英语句单词组成， 其中每一个英语句单词的首字母应该大写， 其余字母小写；规定 Interface 的名称前应该有一个“ I” 。

  9. 实现 Interface 的类一般地应该加上后缀“ Imp” 。 例如，接口 IListener 对应 MyListenerImp 。

• 关于 Class 声明部分的缩进， 可以在如下形式中选择一种。

 

1.  

   1. 常量（ Menifest Variables ）

范例

 

 

说明

 

• 类中常量的声明位于类的最前面， 和类的声明之间 NULL 一行。

• 在声明常量的时候给它付值。

• 规定常量应该被修饰为 public 、 static 和 final ；一般地，把 public 改成 protected 和 private 没有特别大的意义。

• 常量的名称使用 26 个英语句大写字母和下划线“ _” 组成。

• 如无设计上的必要，规定把常量写在 class 中代替把常量写在 interface 中。

 

1.  

   1. 成员变量（ Instance Variables ）

范例

 

 

说明

 

• 在声明变量时应该给它付值。却省对象付值为 null ；整型、长型、浮点型等为 0 ；布尔型为 false 。

• 一般地，类成员变量声明为 private 。如果需要访问，则提供相应的 getter 和 setter 方法。 原则上不通过 instance._variable 的方式访问。如果设计上无继承扩展的考虑，则不应声明为 protected 。规定类成员变量不声明为 friendly 。

• 类成员变量的名称使用 26 个英文字母并且规定使用下划线“ _” 开头。

• 类成员变量是否为 static 应该在设计时决定。一般地，不要把类成员变量声明为 final （即，如果声明为 final ，那么必须声明 static ，作为常量使用）。

 

1.  

   1. 初始块（ Initializer Blocks ）

范例

 

说明

 

• 是否使用 static block 应该在设计时决定。

• 原则上，在声明类成员变量的时候同时进行初始化。 如非必要，不应把声明时的初始化工作在 static block 中做。例如

 

1.  

   1. 构造器（ Constructors ）

范例

 

 

说明

 

• 缺省的构造器必须显示的声明。

• 如无设计上的要求，构造器一律声明为 public ；对于 SingLETon 模式，构造器可以声明为 private ；在不是必要的条件下，不应把构造器声明为 protected 和 friendly 。

• 如果缺省构造器中没有任何代码，则应使用“ //null” 标注。

 

1.  

   1. 属性（ Properties ）

范例

 

说明

 

• 请在类中做 getter 方法、 setter 方法，方法的命名遵循 JavaBean 属性的命名规范。 getter 方法使用“ get + 属性名”； setter 方法使用“ set + 属性名”；对于返回 boolean 的 getter ，使用“ is + 属性名”。

• 与属性对应的类成员变量的名字同属性名相同。 例如，上例中，属性“ name” 对应的类成员变量是“ _name” 。

• 属性名使用 26 个英文字母组成。

• 属性的 getter 和 setter 方法应该为 public 。

 

 

1.  

   1. 方法（ Methods ）

范例

 

 

说明

 

• 方法部分中，每个方法之间有一 NULL 行。

• 一个方法的注释中，包含这个方法的说明、参数说明、返回值说明、例外说明和 @since （或 @deceprated ）。规定，这几个部分在方法中存在的情况下，必须给出相应的说明。例如，如果方法有返回值，则必须给出 @return 的说明。

• 如果方法的参数和返回值有特殊要求，一定要在注释中写明。 例如，

• 关于方法的 @since 和 @deceprated 参见 Class Header 部分。

• 关于参数说明、返回值说明等的对齐，参见 Class Header 部分。

• 关于方法声明的缩进，参见 Class 部分。

• 一个方法声明为 public/protected/private 应该在设计时决定。原则上，如果没有声明为 protected 的理由，就声明为 private ；一般来说，不应将方法声明为 friendly 。

• 方法命名应该使用动宾结构。 例如“ openAccount()” 、“ save()” 、“ printMailingLabel()” 等。

• 关于方法内部的实现：

  1. 一个方法只完成一个特定的功能。（要求是可以用一句话描述这个方法的作用，如果用两句、或两句以上的话才能描述这个方法的作用，说明这个方法过于复杂。）

  2. 方法内部的写法一般地有两种

 

相应的代码举例如下

 

•  

  1. 方法内部的处理流程如下

 

 

• 在方法内部的注释要写明 Why ，而不是 What 。

例

 

• For 循环使用 i 、 j 、 k 作为循环变量。

例如：

• 正确使用空格。例如：

 

• 调整代码风格。例如

 

• 使用 try-catch-finally 结构来 closestream 或 connection 等需要 close 的对象。

这里需要注意的是，在 finally block 中把一个 try-catch 写在一行中是只限于这里的特殊写法，在其他地方不允许把两个大括号写在一行。

 

1.  

   1. 内部类（ Inner Class ）

范例

 

 

说明

 

• 内部类中的变量定义、函数定义的要求和类中的要求相同。

• 如果没有设计上的要求，一个内部类应该被声明为 private 。

• 如果使用一个内部类表示枚举类型，那么可以将它声明为 static 。

• 一般地，不要把一个内部类声明为 abstract 或 final 。

1. 例子

 

（继续）

（继续）

 

 

编码规范

1. 命名规范

   1. Package 命名规范

N_PKG001 Package 名要使用小写字

说明 · 原因

如无特殊规定，请将 Package 名统一成小写字。这是 Java 的一般规则。

例

 

N_PKG002 Package 名要有意义

说明 · 原因

尽量给 Package 命名一个能联想到 Package 内容的名字。如果使用功能 ID 、流水号等来命名 Package 的话，不能马上明白其意思。遵守此规范，将提高代码的易读性。

例

 

N_PKG003 Package 名是不可省略的

说明 · 原因

即使 Package 名长，也请尽量不要省略，而使用易懂的名字。

例

 

1.  

   1. Class 命名规范

N_CLS001 Class 名要能体现其作用

说明 · 原因

Class 名中，请不要使用功能 ID 、流水号等难懂的名字。 Class 名要使用有意义的字符串，以便能联想到其 Class 的内容。这样将提高代码的易读性。

例

 

N_CLS002 Class 名中单词的第 1 个字母要大写

说明 · 原因

请大写 Class 名的第 1 个字母。当 Class 名由多个单词组成时，每个单词的第 1 个字母（段落）都要大写。这是 Java 的一般规则。

例

 

N_CLS003 例外 Class 名的最后要加上“ Exception”

说明 · 原因

对例外 Class 名，请在名字最后加上“ Exception” 。统一此写法，将提高代码的易读性。

例

 

N_CLS004 Interface 名要基于 Class 名

说明 · 原因

Interface 的命名规则基本上要基于 Class 名。统一此写法，将提高代码的易读性。如果需要与 Class 名区分，请在开头加上“ I” 。

例

 

N_CLS005 抽象 Class 名要基于 Class 名

说明 · 原因

抽象 Class 名的命名规则基本上要基于 Class 名。统一此写法，将提高代码的易读性。名字要以“ Abstract” 开始，再加上能联想到 Subclass 名的名字。

例

 

N_CLS006 实装 Class 名要基于 Class 名

说明 · 原因

实装 Class 名的命名规则基本上要基于 Class 名。统一此写法，将提高代码的易读性。如果需要与 Interface 区分，请在最后加上“ Impl” 。

例

 

N_CLS007 在能力附加型的 Interface 名后面加上“ able ”

说明 · 原因

对于 Class 来说，会存在附加某能力的 Interface ，如 Runnable, Cloneable 等。定义能力附加型的 Interface 时，请使用能表示其能力的形容词 ( ～ able ）来命名。统一此写法，将提高代码的易读性。

例

 

N_CLS008 Test Class 名的格式为“测试对象 Class 名 + Test ”

说明 · 原因

Test Class 名的格式为“测试对象 Class 名 ＋ Test” 。统一此写法，将提高代码的易读性。以下的例子是考虑了 JUnit 的例子。

例

 

N_CLS009 进行测试或 Package 测试的所有的 Class 名的格式为“ AllTest ” 或“ Package 名 + Test ”

说明 · 原因

<span styl