java编程规范.docx
《java编程规范.docx》由会员分享，可在线阅读，更多相关《java编程规范.docx（30页珍藏版）》请在冰豆网上搜索。
java编程规范
目 录
1前言4
1.1编写目的4
1.2预期读者4
1.3内容5
2程序格式规范5
2.1Java文件组织格式5
2.2Java代码编写格式10
2.3Java注释格式13
3命名规范18
3.1包、类、文件方法及组件的命名19
3.1.1包的命名19
3.1.2类、接口的命名19
3.1.3文件的命名19
3.1.4方法的命名20
3.1.5组件的命名20
3.2静态常量、变量、参数及异常的命名21
3.3对象的命名21
4编程指导23
4.1编程原则23
4.1.1类、接口23
4.1.2方法23
4.1.3变量23
4.1.4表达式与语句24
4.1.5异常捕捉24
4.1.6其它24
4.2日志25
4.3安全性26
4.4性能26
5质量评审标准27
5.1评审目标27
5.2扣分标准27
6代码范例27
6.1Java代码27
7附录28
7.1有效地使用这些标准28
7.2词汇表28
1前言
1.1编写目的
本文试图提供一套编写高效可靠的Java代码的标准、约定和指导。
它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。
通过遵循和改进这些程序设计标准，使各项目产生的代码有更好的一致性，并提高软件开发团队的生产效率。
本规范适用于采用J2EE规范的项目中，所有项目中的Java代码（含JSP，SERVLET，JAVABEAN，EJB，开发工具生成的代码框架等）均应遵守这个规范。
同时，也可作为其它项目的参考。
要求相关项目都要遵循，并作为项目评审与验收依据。
规范原则：
Ø遵循业界标准
Ø可读性强，意义清楚
Ø整洁严谨、风格统一
1.2预期读者
本书的预期读者包括：
技术管理人员、系统设计人员、系统开发人员、系统测试人员、系统维护人员及其他相关人员。
系统开发人员要求已具有Java编程基础。
读者类型
章节导读
系统设计人员
系统开发人员
系统维护人员
技术管理人员
系统测试人员
质量控制人员
其他
1.3内容
本规范与指导的内容主要有：
Ø结构和文档规范
书写和标记注释的标准方式。
Ø命名规范
命名定义（类名、方法名、变量名等等）的标准方式。
Ø编程指导
描述一些重要的编码规则，可用于纠正以前设计的代码中存在的问题（或不建议使用的方法）和指导新程序的开发，以提高代码的质量。
本文第6章节所描述的代码范例是具体规范的示例，请读者参考。
2程序格式规范
2.1Java文件组织格式
ØJava（*.java）文件组织格式依序包括修订说明、包和导入、类和接口、类的成员等部份。
Ø应把每个Java类放在单独的文件中（除内部类），但对于non-public的类来说，应该包含一个main（）方法，因为它们不能在它们的上下文范围之外被调用。
2.1.1修订说明
Ø文件开头必须说明文件名、标识信息和版权信息。
Ø一个包含作者、日期和修改摘要的修订记录列表说明。
Ø如果文件由多个Class组成，列出每个类的简要描述。
Ø如果文件是一个包的重要切入点，还要简要说明包的结构的基本原理。
示例：
类注释结构
/**
*$CurrentFile
*版权声明GIT版权所有
*关联资源
*修订记录：
*1）更改者：
$Author
*时间：
2009-12-04
*描述：
创建
*/
2.1.2包和导入
Ø先package的名字，import列表紧跟在包的名字后边。
package与import列表之间用空行隔开。
Ø为每个自身独立的项目和一组有关联的方法创建一个新的java包。
Ø为了使package的命名和java包的规范一致，采用目录命名规范。
Øimport语句必须遵循以下导入顺序：
1.jdk标准包
2.java扩展包
3.使用外部库的包
4.使用公司的公共包
5.使用项目的公共包
6.使用其它模块的包
Øimport语句尽量不使用通配符“*”（会加大程序编译时的开销和生成的类文件的大小）。
示例：
packagemon.display;
importjava.io.File;
importjava.util.List;
importjava.lang.reflect.Proxy;
2.1.3类和接口
Ø类、接口定义之前应先进行注释。
注释包括类、接口的目的、作用、功能、继承的父类，实现的接口、实现的算法、使用方法、示例程序等，还可以包括期望改进工作的地方和不希望改变的地方。
示例：
/**
*
|
*
JDK版本：
*@author$Author
*@version$Version
*@see
*@since1.0
*/
publicclass类名[extends父类名][implements接口名]
{
}
或
publicclass类名
[extends父类名]
[implements接口名]
{
}
2.1.4类的成员
Øpublic的成员必须生成JavaDoc文档。
Øprotected、private和package定义的成员如果名字含义明确的话，可以没有注释。
Ø类的所有成员必须在一个地方定义，并按如下顺序定义：
1.成员变量（membervariables）
2.构造函数（classconstructors）（若有多个构建器，参数多的放后面）
3.存取函数（set\getmethods）
4.公有方法（publicmethods）
5.非公有方法（protectedandprivatemethods）
6.主函数（main（），如有必要）
示例：
publicclassExample
{
/**
*保存生成的SQL语句
*/
privateStringBufferstrbufSQL;
/**
*说明构造函数的功能
*/
publicExample（）
{
//功能块
}
/**
*说明方法的功能
*@return说明返回值类型、返回结果情况
*/
publicStringgetSQL（）
{
//功能块
}
/**
*说明方法的功能
*/
privatevoidinit（）
{
//功能块
}
publicstaticmain（String[]args）
{
//测试功能块
}
}
2.2Java代码编写格式
代码编写格式含缩进和对齐、花括号和括号、行长度和宽度、间隔和分段、SQL语句等格式规范与指导原则。
2.2.1缩进和对齐
Ø子功能块应在其父功能块后缩进。
Ø功能块中缩进过深时应将子功能提取出来作为子函数。
Ø关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。
Ø连续赋值时应对齐操作符。
Ø方法的参数较多时应在每个参数后（逗号后）换行并对齐。
Ø控制或循环中的条件比较长时应换行（操作符前）、对齐并注释各条件。
Ø变量定义最好通过添加空格形成对齐，同一类型的变量最好放在一起。
建议代码中以Tab（原则上以4个空格，而不保留Tab键）缩进，开发者请在开发工具中将Tab设置为以空格替代。
示例：
intcount=100;
intlength=0;
StringstrUserName=null;
Integer[]productCode=newInteger
（2）;
//参数对齐
publicConnectiongetConnection（Stringurl,
StringuserName,
Stringpassword）
throwsSQLException.IOException
{
}
//换行对齐
publicfinalstaticStringSQL_SELECT_PRODUCT=“SELECT*”
+“FROMTPRODUCTWHEREPRODID=”
+prodID;
//条件对齐
if（Condition1//当条件一
&&Condition2//并且条件二
||Condition3）//或者条件三
{
//功能块,注意这里对齐方式与上面不一样
}
2.2.2花括号和括号
Ø开括号“{”可以单独作为一行，也可以写在一行的结尾，或者写在一行的开头，若不单独作为一行，则需要用一个空格隔开。
Ø闭括号“}”只能单独作为一行，且与其匹配行对齐，并注释其匹配的功能模块。
如：
publicclassUserManager{
//…………
}
for（inti=0;i//……
}
Ø语句中不要使用无意义的括号。
如：
if （（i） == 42） { // 错误 - 括号毫无意义
if （i == 42） or （j == 42） then // 正确 - 的确需要括号
Ø左括号和后一个字符之间不应该出现空格, 同样, 右括号和前一个字符之间也不应该出现空格。
如：
getUserInfoByUserId（ userId）; // 错误
getUserInfoByUserId（userId）; // 正确
Ø在含有多种运算符时，不要省略必要的括号，以增强运算次序可读性。
建议较长的方法、类及接口等的闭括号后使用“//end…”等标识其结束。
示例：
for（inti=0;i<10;i++）{
for（intj=0;j<100;j++）{
if（i==j）{
……
}//endif判断
}//endj循环
}//endi循环
2.2.3行长度和宽度
Ø单个函数的代码行（不包含注释行）不允许超过100行。
Ø单个类的代码行（包含注释行）不允许超过1500行。
Ø行宽应控制在80~120列之间。
单个函数的代码行超过100行时可以使用子函数等将相应功能抽取出来；单个类的代码行超过1500行时可以将相应功能的代码重构到其它类中；长语句行宽超过80列时可以在逗号后或操作符前折行，并比原语句再缩进4个空格。
2.2.4间隔和分段
Ø类、方法及功能块间等应以空行相隔。
Ø操作符两端应各空一个字符。
建议采用一个空行来分隔代码的逻辑组，例如控制结构，采用两个空行来分隔成员函数定义；相应独立的功能模块间可使用注释行间隔，并注明相应内容。
2.3Java注释格式
开发人员必须重视注释的编写。
（注释代码的方式很大地影响着开发人员的工作效率以及所有维护改进代码的后继开发者的工作效率。
在软件开发过程中及早注释代码，会促使开发人员在开始撰写代码之前仔细考虑这些代码，从而带来更高的工作效率。
而且，当开发人员重新阅读数天前或者数星期前所写的代码时，可以很容易地判断出当时你是怎么想的，因为这一切都有记录。
）
注释一般遵循以下规则：
Ø注释应该增加代码的清晰度。
Ø保持注释的简洁
Ø如果你的程序不值得注释，那么它也很可能也不值得运行。
Ø边写代码边注释，修改代码同时修改相应注释，以保证注释与代码的一致性
Ø在必要的地方注释，注释量要适中。
注释的内容要清楚、明了，含义准确，防止注释二义性。
保持注释与其描述的代码相邻，即注释的就近原则。
Ø注释信息不仅要包括代码的功能，还应给出原因。
2.3.1注释语句类型
Ø允许以下三种注释语句风格及混用：
1）以/**开始，*/结束的文档注释；
2）以/*开始，以*/结束的C语言风格注释；
3）以//开始，代码行上一行的单行注释及变量或括号后面的尾注释。
Ø注释语句描述性文字使用中文来表述，并尽量减少歧义。
Ø有关类、变更或方法的注释语句须在相应定义之前。
建议在IDE中使用Java代码模板给类进行注释。
下表是对各类注释语句建议用法的一个概括，也给出了几个例子。
注释语句类型
用法
示例
文档注释
在接口、类、成员函数和字段声明之前紧靠它们的位置用文档注释进行说明。
文档注释由javadoc处理，为一个类生成外部注释文档，如下所示。
/**
Customer（顾客）顾客是指作为我们的服务及产品的销售对象的任何个人或组织。
@authorXXX
*/
C语言风格注释
采用C语言风格的注释语句将无用的代码注释掉。
保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。
/*
这部分代码已被它前面的代码替代，所以于2009年12月4日被Jack.Buff注释掉。
如果两年之后仍未用这些代码，将其删除。
...（源代码）
*/
单行注释
在成员函数内部采用单行注释语句对业务逻辑、代码片段和临时变量声明进行说明。
//因为让利活动
//从2009年12月开始，
//所以给所有超过$1000的
//发货单5%的折扣。
2.3.2类和接口的注释
Ø用javadoc规范来写/**…**/注释，注释用于描述类的功能、指令用法和用例说明，示例主要是在强调注释格式下使用HTML标签增强JavaDoc的可读性。
示例（带有标签格式的HTML格式）：
/**
*
类描述说明
*
*例子：
*Windowwin=newWindow（parent）;
*win.show
*
*
JDK版本：
JDK1.5
*@author$Author
*@version$Version
*@see
*@since1.0
*/
publicclassWindowextendsBaseWindow{
/**
*方法说明
*/
publicvoidshow（）{
…
}
}
下表是对各类标记的一个概括。
标记
用于
目的
@authorname
类、
接口
说明特定某一段程序代码的作者。
每一个作者各有一个标记。
@deprecated
类、
成员函数
说明该类的应用程序编程接口（API）已被废弃，因此应不再使用。
@exceptionnamedescription
成员函数
说明由成员函数发出的异常。
一个异常采用一个标记，并要给出异常的完整类名。
@paramnamedescription
成员函数
用来说明传递给一个成员函数的参数，其中包括参数的类型/类和用法。
每个参数各有一个标记。
@returndescription
成员函数
若成员函数有返回值，对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
@since
类
说明自从有JDK1.1以来，该项已存在了多长时间。
@seeClassName
类、接口、成员函数、字段
在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
@seeClassName#memberfunctionName
类、接口、成员函数、字段
在文档中生成指向特定成员函数的超文本链接。
可以并且应该采用完全合法的类名。
@versiontext
类、接口
说明特定一段代码的版本信息。
最常用的类注释JavaDoc标记：
标记
用于
目的
@authorname
类、
接口
说明特定某一段程序代码的作者。
每一个作者各有一个标记。
@since
类
说明自从有JDK1.1以来，该项已存在了多长时间。
@seeClassName
类、接口、成员函数、字段
在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
@versiontext
类、接口
说明特定一段代码的版本信息。
最常用的方法注释JavaDoc标记：
标记
用于
目的
@exceptionnamedescription
成员函数
说明由成员函数发出的异常。
一个异常采用一个标记，并要给出异常的完整类名。
@paramnamedescription
成员函数
用来说明传递给一个成员函数的参数，其中包括参数的类型/类和用法。
每个参数各有一个标记。
@returndescription
成员函数
若成员函数有返回值，对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
2.3.3类变量的注释
Ø用javadoc规范及/**…*/注释实例变量和静态变更的用法、约束。
示例：
/**
*计数器：
值范围在[0,100]
*/
protectedintcount;
2.3.4方法的注释
Ø用javadoc规范及/**…*/注释方法的用途、功能、算法摘要、指令用法和注意事项，复杂算法在方法体内用/*…*/注释。
示例：
/**
*执行查询
*该方法调用Statement的executQuery（sql）方法并返回ResultSet结果集
*@paramsql标准的SQL语句
*@returnResultSet结果集，若查询失败则返回null
*@throwsSQLException当查询数据库时可能引发此异常
*/
publicResultSetexecuteQuery（Stringsql）throwsSQLException{
//Statement和SQL语句都不能为空
if（stmt!
=null&&!
StringUtil.isEmpty（sql））{
//返回查询执行结果
Returnstmt.executeQuery（sql）;
}
returnnull;
}
3命名规范
Java应用程序的命名标准主要分为三个方面：
类、变量及方法。
命名基本原则如下：
Ø必须以字母开头。
Ø采用大小写混合，类和接口的首字母以及任何中间单词的首字母应用采用大写。
Ø使用可以准确说明变量/字段/类的完整的英文描述符。
Ø尽量采用应用领域的术语，如顾客用customer而不用client。
Ø不能与受到限制的关键字同名。
Ø尽量少用缩写,如果用了，则尽量在整个项目中统一
Ø长度不超过15个字母，最长不能超过255个字符。
Ø避免使用下划线（静态常量除外）
Ø禁止使用拼音
Ø各个项目组需要提供具体符合本项目的命名规范表，此表将作为命名规范的实际补充
3.1包、类、文件方法及组件的命名
3.1.1包的命名
Ø包的名字由一个或多个小写单词组成，其中com.git作为基础类保留。
包的命名采用目录命名规范并考虑使用JavaLanguageSpecificaton中的标准作为前缀（如:
edu,org,com）。
参见2.1.1包格式规范，建议在项目中以如下方式命名：
git.项目名称.模块名称
3.1.2类、接口的命名
Ø类、接口的名字一般采用名词，各单词首字母大写，其它字母小写。
而缩写则全部字母大写。
建议对接口的具体实现类以Imp结尾，对异常类以Exception结尾。
示例：
publicclassStringCompareImpimplementsCompare
publicclassSampleExceptionextendException
3.1.3文件的命名
Ø文件名必须与类名、接口名一致。
因为Java编译器要求Java文件名与public类名相同。
如上示例：
publicclassStringCompareImpimplementsCompare
对应的文件名为：
StringCompareImp.java
3.1.4方法的命名
Ø方法的命名应采用完整的英文描述符，大小写混用；第一个单词首字母小写，所有中间单词的第一个字母大写。
Ø方法参数建议顺序：
（被操作者，操作内容，操作标志，其他）
建议方法名字的第一个单词采用强烈动作色彩的动词，以构成动宾关系的记。
取值使用get前缀，赋值使用set前缀，判断使用is（has）前缀，插入使用insert前缀，删除使用delete前缀，生成使用new前缀，等等。
示例1：
getName（）
setSarry（）
isLongCard（）
示例2：
publicStringreplaceString（StringsourceStr,//源字符串
StringoldStr,//被替换字符串
StringnewStr）{//目标字符串
…
}
3.1.5组件的命名
Ø使用完整的英文描述来说明组件的用途，末端应接上组件类型。
如：
okButton,customerList,fileMenu
3.2静态常量、变量、参数及异常的命名
Ø静态常量：
全部采用大写字母，单词之间用下划线分隔。
Ø变量：
第一个字母必须是小写，任何中间单词的首字母大写。
若采用拼音，则所有字母一律用小写。
Ø数组：
采用下面的方式来命名：
objectType[]变量名;
Ø参数：
使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字。
对于使用O/R映射、开发工具自动生成常（变）量等时，可以不采用本节要求的常、变量命名规范。
建议除循环内部计算用i、j、k外，常、变量不要使用单个字符。
示例：
privatefinalstaticStringTAG_OPERATION="tagPreOperation";
privateintinnerSeqNo=0;
privateStringaccount;//账号
String[]args；
byte[]buffer；
bytebuffer[]//错误定义
setRoleplayerId（StringroleplayerId）{
this.roleplayerId=roleplayerId;
}
3.3对象的命名
Ø通常情况下，对象的名称与类的名称相同，但所有字母均为小写，类名过长的采用缩写。
Ø常用的对象都有其特有得命名方式。
Ø对于需要创建一个类的多个对象的情况，则对象的名称由该类名称的缩写（大写）和表明创建的对象意义的单词（小写）组合而成。
示例：
SimilarDatasimilardata
Statementstmt
Connectioncon
Exceptione或ex
ResultSetrs
4编程指导
4.1编程原则
4.1.1类、接口
Ø类的划分粒度要适当，不宜继承太深。
建议一个类只做一件事
升级会员 