Java编码规范v10.docx
《Java编码规范v10.docx》由会员分享，可在线阅读，更多相关《Java编码规范v10.docx（79页珍藏版）》请在冰豆网上搜索。
Java编码规范v10
Java编码规范
（JavaCodingStandard）
V1.02011/9/16
修改履历
Ver
修改时间
修改的图表
和章节编号
状态
修改概要说明
修改人
1.0
2011/9/16
N
向涛
注：
状态中，N是新建，A是追加，M是修改，D是删除。
目录
目的4
范围4
前提条件5
1代码风格5
1.1一般格式说明5
1.2基本结构5
2代码结构6
2.1变更历史记录6
2.2Package声明8
2.3Import声明9
2.4ClassHeader10
2.5Class11
2.6常量（MenifestVariables）13
2.7成员变量（InstanceVariables）14
2.8初始块（InitializerBlocks）14
2.9构造器（Constructors）15
2.10属性（Properties）16
2.11方法（Methods）17
2.12内部类（InnerClass）21
3例子22
编码规范23
1命名规范23
1.1Package命名规范23
1.2Class命名规范23
1.3Method命名规范25
1.4变量命名规范27
2代码风格规范29
2.1控制语句风格规范29
2.2命令语句风格规范31
2.3声明语句风格规范34
3书写格式规范36
4设计规范39
4.1质量测定基准（Metrics）规范39
4.2Class设计规范39
4.3Method设计规范41
4.4变量设计规范42
5Java语言规范44
5.1Object整体规范44
5.2修饰符规范46
5.3Javadoc规范48
5.4Import规范49
5.5字符串规范49
5.6数值规范52
5.7日期规范52
5.8集合规范52
5.9Stream规范53
5.10例外规范54
5.11线程规范55
5.12Servlet规范58
5.13EJB规范60
附录1INDEX62
1 BD62
2 SD62
3 DD62
4 PG62
5 PT64
6 IT64
目的
本文是博微广成研发部的规范文件。
本文的目的是统一Java的编码风格、提高代码质量。
范围
本文的适用范围是项目的编码阶段，同时也适用于项目的设计阶段和测试阶段。
本文的适用项目是使用Java语言开发的项目。
本文适用于掌握Java语言开发的开发人员。
前提条件
本文的第一条规则是任何规则都有例外。
如果在编码中有违反本文规则的地方，请加上注释。
本文中的一些约定对您现在的编码习惯可能并没有绝对的好处，它们仅仅为了统一代码风格。
Java编码规范概要
Java代码风格概要说明如下。
1代码风格
1.1一般格式说明
▪除字符串和注释内以外，代码中的空格一律为半角。
▪代码中不应有[TAB]字符（除字符串内），需要[TAB]字符的地方一律替换成4个空格。
▪代码中换行和DOS系统相同，为/r/n。
▪代码应该有缩进，缩进为4个空格。
▪缺省的一行代码最大长度为80个半角字符，如果超过这个长度就需要换行。
一般的情况下，换行后应缩进四格。
▪任何可以省略大括号的地方都不应省略大括号。
1.2基本结构
一个类/接口的基本结构应该是这样的。
初始Block（InitializerBlocks）
以下依次说明。
2代码结构
2.1变更历史记录
范例
/**
*MyClass.java
*
*功能：
（一句话描述类的功能）
*类名：
MyClass
*
*ver更新日责任人更新内容
*──────────────────────────────────
*V1.00'2011-01-01程序猿初版
*V1.01'2011-03-20程序猿修改
*V1.10'2011-06-04程序媛修改
*
*Copyright（c）GCTECAllRightsReserved.
*LICENSEINFORMATION
*/
说明
▪“文件”的第一行是正文，在它前面没有NULL行。
▪需要修改的部分已经用粗体标出。
▪在“变更历史记录”中有一部分是版本编号（ver），具体的编号方法依从项目制定的版本变更策略。
▪在“变更历史记录”的版权信息中，有关于版权所有者的描述。
其中的“GCTEC”，还未最后确定名称。
▪如果项目中有相关的许可信息（license），这些信息可以在“LINCENSEINFORMATION”处加入。
▪如果项目中，变更履历使用CVS、SVN等源码管理系统维护，那么此“变更历史记录”可以精简为
/**
*$Header:
/xxx/xxx/xxx.java$
*$Revision:
1.4.1$
*$Date:
2011/09/1602:
23:
08$
*
*Copyright（c）gctecAllRightsReserved.
*LICENSEINFORMATION
*/
2.2Package声明
范例
packagecom.gctec.myapp.mypack;
说明
▪package遵循以下命名规则：
1.package名全部为小写字母，中间用“.”分割。
2.package名中禁止使用除小写英语句半角字母以外的任何字符，但是根据需要可以使用下划线“_”。
例如
packagecom.gctec.my_app.mypack;
3.标准的package名可以分为三部分：
<公司名>.<应用程序名>.<包名>。
其中“公司名”部分可以是“公司名称+部门名称”。
例如
packagecom.gctect.dev.myapp.mypack;
根据需要“公司名”部分也可省略。
其中“应用程序名”部分可以是“应用程序名称+子程序名称”。
例如
packagecom.gctec.myapp.subapp.mypack;
一般来说，“应用程序名”部分不能省略。
其中“包名”部分应该根据程序设计的包结构来定义；“包名”这部分可以根据需要省略。
▪通常，“Package声明”部分不能省略。
如果是应用程序比较简单，可以简化package的名称。
例如，简单的试验使用的类，可以命名为“myapp.test”或者“test”；如果是一个小程序，可以命名为“myapp”或者“main”。
2.3Import声明
范例
importjava.util.HashMap;
importjava.util.Map;
importjavax.servlet.http.HttpServletRequest;
importjavax.servlet.http.HttpServletResponse;
importorg.apache.log4j.Appender;
importorg.apache.log4j.Category;
importcom.gctec.myapp.thatpack;
説明
▪“Import声明”内部没有NULL行。
▪“Import声明”的次序是
java.*->javax.*->中间件、库等提供的package->程序中的package
▪Import需要指出import哪一个类，禁止import整个package。
例如
importjava.util.*;//错误
importjava.util.HashMap;//正确
▪通常程序内部用到的package都是用import语句声明在程序头部；原则上，程序内部不再出现没有import声明的类。
例如
java.io.Filefile=newjava.io.File（“test.txt”）;//错误
Filefile=newFile（“test.txt”）;//正确
但是会混淆的声明应该在程序中特别指出是那一个package中的。
例如：
importjava.util.Date;
importjava.sql.Date;
…
java.util.Datedate=newjava.util.Date（）;
▪程序中用到的类应该在Import中声明，但是程序中没有用到的类不要出现在Import中。
例如
importjava.util.HashMap;->删除
…
（程序中未使用HashMap这样的类）
2.4ClassHeader
范例
/**
*（这里用一句话描述这是一个什么样的类，格式：
本类是XXXXXX。
）
*（这里用1~5句话描述这个类的功能是什么。
-可选）
*（这里介绍这个类涉及到的相关信息。
譬如，专有名词、概念的简单解释。
-可选）
*（这里介绍这个类在系统中的角色，以及如何和其他类交互。
-可选）
*（这里介绍这个类的WHY，即为什么会存在这样一个类。
-可选）
*（这里介绍这个类的使用方法。
-可选）
*（这里是使用这个类的sample。
-可选）
*（这里是使用这个类的注意事项。
-可选）
*
*@author程序猿
*@versionVer1.22011-09-16修订
*@sinceCodingExampleVer1.1
*
*@seeYourClass,HisClass
*@deprecated（这里写deprecated的信息）
*/
说明
▪“ClassHeader”可以分为3部分——说明部分、版本信息和其他信息，中间使用NULL行分割。
▪程序中的每一个类都必须有Class注释。
根据需要，Class注释中除了说明部分不能省略外，版本信息和其他信息都可以省略。
▪Class注释中的说明部分的写法参考范例，根据需要，可以省略其中的一些说明部分（可省略的部分后标有可选）。
▪Class注释的版本信息中，除@since可以根据需要省略外，其他的都不可省略。
▪Class注释的版本信息要上下对齐。
对齐
*@author程序猿
*@versionVer1.22011-09-16修订
*@sinceCodingExampleVer1.1
▪@version信息的结构是“Ver<版本><日期><状态>”。
其中“版本”是项目版本，具体依据项目制定的版本变更规范；其中“日期”为此文件最后一次修改的日期；其中状态有两种选择“新建”和“修订”。
▪@since信息的结构是“<项目名称>Ver<版本>”。
其中“项目名称”可以是项目的全称也可以是项目的简称，但是要注意在整个项目中这个名称应该不变；其中“版本”是表示这个类从哪个版本开始存在。
▪Class注释的其他信息中，@see和@deprecated都可以省略。
▪@deprecated的说明信息的结构是“<在哪个版本中不推荐使用><使用哪个类替代>”。
例如
*@deprecatedCodingExample1.2中，不推荐此Class。
此Class的功能，被替换为com.gctec.myapp.AnotherClassClass了。
*@deprecatedCodingExample1.2中，不推荐此Class。
没有替补。
根据需要，选择上面两种表述方法中的一种，替换划线部分，做成需要的@deprecated信息。
2.5Class
范例
publicclassMyClassextendsSuperClassthrowsException{
//dosth.（ClassBody）
}
说明
▪ClassBody应该缩进4格。
▪Class声明部分可以分为4部分——Class前缀、Class名、扩展信息和例外信息。
▪Class声明的结构是“[public/protected/private][final/abstract/static/strictfp]class/interface<类名>[extends…][implements…][throws…]”。
4.关于public/protected/private，在一般情况下（指Top-LevelClass），规定所有的类都应该显式声明为public。
5.关于final，如果项目中没有显式地强调安全性，规定禁止将一个类声明为final。
6.关于abstract，如果一个类可以声明成interface，规定禁止把类声明为abstract；如果一个类中没有abstract的方法，规定禁止把类声明为abstract。
7.不能继承声明为static的类。
8.如果项目中不涉及到严格的数据运算（譬如，强调float和double的运算），那么禁止把类声明为strictfp。
▪Class的命名遵循以下规则。
9.Class的名称应该是一个名词短语。
可以是“形容词/名词+名词”的形式。
例如InputDataStream、Developer、OrderItem等。
10.Class的名称由1个或1个以上的英语句单词组成，其中每一个英语句单词的首字母应该大写，其余字母小写。
11.规定Class名称只能由26个英文字母组成。
12.Class命名应该具有一致性。
（一致性是指，如果在设计阶段确定了一个实体，那么和这个实体相关的Class应该具有一致的名称。
举例来说，“用户”这个实体可以被称作User、Account或者Person。
如果决定使用User来表示这个实体的话，则相应的Class名应该是UserFile和UserFileParser等，避免在系统中出现既有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.实现Interface的类一般地应该加上后缀“Imp”。
例如，接口IListener对应MyListenerImp。
▪关于Class声明部分的缩进，可以在如下形式中选择一种。
publicclassMyClassextendsYourClassimplementsTheirClass
throwsOurException
{
publicclassMyClassextendsYourClassthrowsOurException,
TheirException,
AnotherException
{
publicclassMyClassextendsYourClassimplementswhichIF,
whatIF,
whereIF
{
publicclassMyClassextendsYourClassimplementswhichIF,
whatIF,
whereIF
throwsOurException,TheirException,AnotherException
{
2.6常量（MenifestVariables）
范例
/**
*（用一句话描述这个变量表示什么）
*
*@sinceCodingExampleVer1.1
*/
publicstaticfinalintMAX_LENTH=25;
publicstaticfinalintMax_Lenth=25;
说明
▪类中常量的声明位于类的最前面，和类的声明之间NULL一行。
▪在声明常量的时候给它付值。
▪规定常量应该被修饰为public、static和final；一般地，把public改成protected和private没有特别大的意义。
▪常量的名称使用26个英语句大写字母和下划线“_”组成。
▪或者首字母大写和下划线“_”组成。
▪如无设计上的必要，规定把常量写在class中代替把常量写在interface中。
2.7成员变量（InstanceVariables）
范例
/**
*（用一句话描述这个变量表示什么）
*
*@sinceCodingExampleVer1.0
*/
privateStringname=null;
说明
▪在声明变量时应该给它付值。
却省对象付值为null；整型、长型、浮点型等为0；布尔型为false。
▪一般地，类成员变量声明为private。
如果需要访问，则提供相应的getter和setter方法。
原则上不通过instance._variable的方式访问。
如果设计上无继承扩展的考虑，则不应声明为protected。
规定类成员变量不声明为friendly。
▪类成员变量的名称使用26个英文字母开头。
▪类成员变量是否为static应该在设计时决定。
一般地，不要把类成员变量声明为final（即，如果声明为final，那么必须声明static，作为常量使用）。
2.8初始块（InitializerBlocks）
范例
/**
*（这里描述这部分代码的作用）
*
*@sinceCodingExampleVer1.0
*/
static{
//本体处理
}
说明
▪是否使用staticblock应该在设计时决定。
▪原则上，在声明类成员变量的时候同时进行初始化。
如非必要，不应把声明时的初始化工作在staticblock中做。
例如
privateString_name;
static{
name=“DefaultName”; //错误
}
privateStringname=“DefaultName”;//正确
2.9构造器（Constructors）
范例
/**
*（这里描述这个构造器的作用）
*
*@sinceCodingExampleVer1.0
*/
publicMyClass（）{
//本体处理
}
说明
▪缺省的构造器必须显示的声明。
▪如无设计上的要求，构造器一律声明为public；对于Singelton模式，构造器可以声明为private；在不是必要的条件下，不应把构造器声明为protected和friendly。
▪如果缺省构造器中没有任何代码，则应使用“//null”标注。
publicMyClass（）{} //错误
publicMyClass（）{//正确
//null
}
2.10属性（Properties）
范例
/**
*获取名称。
*
*@returnString名称
*@sinceCodingExampleVer1.0
*/
publicStringgetName（）{
returnname;
}
/**
*设置名称。
*
*@paramname名称
*@sinceCodingExampleVer1.0
*/
publicvoidsetName（Stringname）{
this.name=name;
}
说明
▪请在类中做getter方法、setter方法，方法的命名遵循JavaBean属性的命名规范。
getter方法使用“get+属性名”；setter方法使用“set+属性名”；对于返回boolean的getter，使用“is+属性名”。
▪与属性对应的类成员变量的名字同属性名相同。
例如，上例中，属性“name”对应的类成员变量是“name”。
▪属性名使用26个英文字母组成。
▪属性的getter和setter方法应该为public。
▪使用一些编辑器如eclipse时，推荐自动生成getter和setter。
2.11方法（Methods）
范例
/**
*（这里用一句话描述这个方法的作用）
*（这里描述这个方法适用条件–可选）
*（这里描述这个方法的执行流程–可选）
*（这里描述这个方法的使用方法–可选）
*（这里描述这个方法的注意事项–可选）
*
*@paramfile设定文件
*@returnDocumentDOM对象
*@throwsIOException设定文件中缺少信息时
*@sinceCodingExample Ver1.1
*/
publicDocumentparse（Filefile）throwsIOException{
//1.取得处理要求的所有数据/检查数据的有效性
//2.处理本体
//3.返回/保存结果
}
说明
▪方法部分中，每个方法之间有一NULL行。
▪一个方法的注释中，包含这个方法的说明、参数说明、返回值说明、例外说明和@since（或@deceprated）。
规定，这几个部分在方法中存在的情况下，必须给出相应的说明。
例如，如果方法有返回值，则必须给出@return的说明。
▪如果方法的参数和返回值有特殊要求，一定要在注释中写明。
例如，
*@paramfile设定文件，NULL也可
*@returnMap ActionMapping、key->String、value->String
▪关于方法的@since和@deceprated参见ClassHeader部分。
▪关于参数说明、返回值说明等的对齐，参见ClassHeader部分。
▪关于方法声明的缩进，参见Class部分。
▪一个方法声明为public/protected/private应该在设计时决定。
原则上，如果没有声明为
升级会员 