JAVA开发编码规范12.docx

JAVA开发编码规范12.docx

《JAVA开发编码规范12.docx》由会员分享，可在线阅读，更多相关《JAVA开发编码规范12.docx（19页珍藏版）》请在冰豆网上搜索。

JAVA开发编码规范12

JAVA开发编码规范

版本说明

版本

制订人

制订日期

主要内容

前言4

目的4

1.2、范围4

格式规范5

2.1缩进5

2.2换行5

2.3间隔5

2.4对齐5

2.5括号6

三、注释规范6

3.1基本原则6

3.2文件注释6

3.3JavaDoc注释7

3.4失效代码注释8

3.5代码细节注释8

3.6注释的格式8

3.7注释的内容9

3.8Null规约9

4命名规范（NamingConventions）10

4.1基本约定10

4.2文件、包11

4.3类、接口11

4.4字段11

5编程规范（ProgrammingConventions）12

5.1基本规范12

5.2类与接口13

5.3方法13

5.4错误与异常14

5.5JDK5.0及后续版本15

5.6性能与安全15

6自动代码检查和修正17

6.1为了编码的一致性，统一将Workspace中的编码方式设置为UTF-8编码17

6.2使用统一的代码模板17

前言

目的

本规范的目的是通过建立编码规范统一每个开发人员的编码习惯，提高程序的可靠性、可读性、可修改性、可维护性及一致性，增加团队合作开发效率，为各项目组之间或项目组内成员之间的技术交流提供一个方便统一的方式。

1.2、范围

本规范适用于公司内所有运用JAVA技术的软件项目、产品等的设计、开发以及维护、升级等。

本规范适用于公司所有JAVA软件开发人员。

本规范建议的开发环境与工具如下：

IDE:

Eclipse3.3.2以后版本

插件:

MyEclipse6.0以后版本

JDK:

SunJDK1.5

格式规范

对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使软件开发团队中的程序员能够很容易地理解代码。

代码的组织和风格的基本原则是：

便于自己的开发，易于与他人的交流。

因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。

2.1缩进

使用TAB缩进，而不是空格键——将缩进2，4，8字符的选择权留给阅读者。

子功能块当在其父功能块后缩进。

当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。

2.2换行

页宽应该设置为80字符。

一般不要超过这个宽度,这会导致在某些机器中或打印（A4）时无法以一屏来完整显示,但这一设置也可以灵活调整。

在任何情况下,超长的语句应该在一个逗号后或一个操作符。

前折行。

一条语句折行后,应该比原来的语句再缩进一个TAB，以便于阅读。

2.3间隔

类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。

操作符两端应当各空一个字符以增加可读性。

相应独立的功能模块之间可使用注释行间隔，并标明相应内容。

2.4对齐

关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。

连续赋值时应当对齐操作符。

当方法参数过多时在适当的参数后（逗号后）换行并对齐。

当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。

2.5括号

括号中的语句应该单独作为一行，左括号"{"当紧跟其语句后，右括号"}"永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。

较长的方法以及类、接口等的右括号后应使用//end...等标识其结束。

如:

类的结束符：

}//endClassName，

方法结束符：

}//endmethodName（），

功能块结束：

}//endif...userNameisnull?

循环快结束：

}//endfor...everyuserinuserList

不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。

if，for，while语句只有单句时，如果该句可能引起阅读混淆，需要用"{"和"}"括起来，否则可以省略。

三、注释规范

3.1基本原则

基本原则：

注释应该增加代码的清晰度。

代码注释的目的是要使代码更易于被其他开发人员等理解。

注释信息不仅要包括代码的功能，还应给出原因。

除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。

3.2文件注释

在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。

并在其中使用版本仓库标记自动跟踪版本变化及修改记录等信息。

注意是标准的C-Style/*...*/注释而不是/*...*/形式的JavaDoc注释，在ECLIPES中使用CODETEMPLATES会自动添加，如下。

/*

*@（#）Test1.java

*CreatedDate:

Sep11,2008

*

*Copyright（c）JiangsuEcodeCo.,Ltd

*

*Thissoftwareistheconfidentialandproprietaryinformationof

*JiangsuEcodeCo.,Ltd.（"ConfidentialInformation"）.Youshallnot

*disclosesuchConfidentialInformationandshalluseitonlyinaccordance

*withthetermsofthelicenseagreementyouenteredintowith

*JiangsuEcodeCo.,Ltd.

*/

3.3JavaDoc注释

对类、方法、变量等的注释需要符合JavaDoc规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML标记格式化注释，以使生成的JavaDoc易阅读和理解。

类注释中当包含版本和作者信息，使用版本仓库的标记自动跟踪版本变化和修改记

录，如下。

/**

*用于示例的类

*

*@authorguoqiang

*@version$Rev$

*$Id:

Test1.java,v1.22008/09/1702:

25:

08cvsrootExp$

*/

publicclassTest1{

privatestaticfinalLoggerlogger=Logger.getLogger（Test1.class）;

/**

*一个测试的方法

*@paramuserid用户编号

*@return返回用户信息对象，若无该用户信息，则返回null

*/

privateUserInfogetStrings（Integeruserid）{

……………

returnuserInfo;

}

}

3.4失效代码注释

由/*...*/界定，标准的C-Style的注释。

专用于注释已失效的代码。

/*username="";

password="";

currentCar="";

logined=false;

attributes=newHashMap（）;

attributes.put（"title","hello"）;*/

失效注释快捷键是Ctrl+Shift+/，取消注释是Ctrl+Shift+\

3.5代码细节注释

由//界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注

释的失效代码分开除了私有变量外，不推荐使用行末注释。

//设置CarBean

for（inti=0;i<20;i++）

{

//首先需要生成实例

CarBeanbean=newCarBean（）;

bean.setBaseprice（11）;

bean.setDescription（"aa"）;

bean.setName（"1111"）;

cdao.save（bean）;

}

3.6注释的格式

●注释中的第一个句子要以（英文）句号、问号或者感叹号结束。

Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。

●为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@seexxx.MyClass，@seexx.MyClass#find（String）。

●Class必须以@author作者名声明作者，不需要声明手工指定@version与@date，由版本管理系统保留此信息。

●如果注释中有超过一个段落，用

分隔。

●示例代码以

//

●标识（javakeyword,class/method/field/argument名，Constants）以包裹。

●标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。

3.7注释的内容

●对于API函数如果存在契约，必须写明它的前置条件（precondition），后置条件（postcondition），及不变式（invariant）。

●对于调用复杂的API尽量提供代码示例。

●对于已知的Bug需要声明。

●在本函数中抛出的uncheckedexception尽量用@throws说明。

●注释中的每一个单词都要有其不可缺少的意义，注释里不写"@paramname-名字"无意义的内容。

●注释的标签必须有内容，不能存在空的@paramname，空的@return。

3.8Null规约

如果方法允许Null作为参数，或者允许返回值为Null，必须在JavaDoc中说明。

如果没有说明，方法的调用者不允许使用Null作为参数，并认为返回值是NullSafe的。

/**

*

*@paramactionEvent买车按钮的动作事件

*@throwsException一般异常

*/

publicvoidbuyCar（ActionEventactionEvent）throwsException

{

}

4命名规范（NamingConventions）

规范的命名能使程序更易阅读，从而更易于理解。

它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。

4.1基本约定

●使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。

例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。

●采用该领域的术语。

如果用户称他们的“客户”（clients）为“顾客”（customers），那么就采用术语Customer来命名这个类，而不用Client。

●采用大小写混合，提高名字的可读性。

一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。

包名全部小写。

●尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，应用程序（application）可缩写成app等，严禁滥用缩写。

●避免使用长名字（最好不超过25个字母）。

●避免使用相似或者仅在大小写上有区别的名字。

●避免使用数字，但可用2代替to，用4代替for等，如：

go2Jsp。

●遇到缩写如XML时，仅首字母大写，即loadXmlDocument（）而不是loadXMLDocument（）。

4.2文件、包

●文件名当与其类严格相同，所有单词首字母大写。

●包名一般以项目或模块名命名，少用缩写和长名，一律小写。

●基本包：

com.candur，所有包、文件都从属于此包。

●包名按规则组成：

[基本包].[项目名].[模块名].[子模块名]...

●不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。

4.3类、接口

所有单词首字母大写。

使用能确切反应该类、接口含义、功能等的词。

一般采用名词。

接口可以可以在名词前加大写I，如IBookDao,，BookDaoIF。

4.4字段

4.4.1常量

采用完整的英文大写单词，在词与词之间用下划线连接，如：

DEFAULT_VALUE

4.4.2变量和参数

对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用strXXX，boolean使用isXXX，hasXXX等等。

除第一各个单词外其余单词首字母大写。

对私有实例变量可使用下划线“_”前缀，但在其存取方法中则应该将其前缀去掉。

局部变量及输入参数不要与类成员变量同名（get/set方法与构造函数除外）。

4.4.3组件/部件

应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则页面部件名建议命名为：

btnOK、lblName或okBtn、nameLbl。

（II）

4.4.4集合

一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。

命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。

如：

__

5编程规范（ProgrammingConventions）

声明的基本原则是遵守Java语言规范，并遵从习惯用法。

。

5.1基本规范

●当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring的Assert系列函数。

●隐藏工具类的构造器，确保只有static方法和变量的类不能被构造实例。

●变量，参数和返回值定义尽量基于接口而不是具体实现类。

如：

●代码中不能使用System.out.println（），e.printStackTrace（），必须使用logger打印信息。

5.2类与接口

5.2.1基本原则

●类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。

一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User来存放用户信息，而用UserDAO来对用户信息进行数据访问操作（比如存取数据库），用UserBroker来封装用户信息的业务操作等等。

●多使用设计模式，随时重构。

●多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。

●将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。

●将不希望被实例化的类的缺省构造方法声明成private。

5.2.2抽象类与接口

一般而言：

接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java集合等实现。

多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。

5.2.3继承与组合

尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。

5.2.4构造函数和静态工厂方法

当需要使用多个构造函数创建类时，建议使用静态工厂方法替代这些构造方法。

5.3方法

5.3.1基本原则

l一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩

小其可见性。

l避免用一个类是实例去访问其静态变量和方法。

l避免在一个较长的方法里提供多个出口。

5.3.2参数和返回值

l避免过多的参数列表，尽量控制在5个以内，若需要传递多个参数时，当使

用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性。

l参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高系统的可扩展性。

5.4错误与异常

5.4.1基本原则

l通常的思想是只对错误采用异常处理：

逻辑和编程错误，设置错误，被破坏的

数据，资源耗尽，等等。

l通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何

异常。

l最小化从一个给定的抽象类中导出的异常的个数。

l对于经常发生的可预计事件不要采用异常。

l不要使用异常实现控制结构。

l确保状态码有一个正确值。

l在本地进行安全性检查，而不是让用户去做。

l若有finally子句，则不要在try块中直接返回，亦不要在finally中直接返

回。

5.4.2已检查异常与运行时异常

l已检查异常必须捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。

l对可预见的运行时异常当进行捕捉并处理，比如空指针等。

通常，对空指针的

判断不是使用捕捉NullPointException的方式，而是在调用该对象之前使用判

断语句进行直接判断。

l建议使用运行时异常（RuntimeException）代替已检查异常（CheckedException）。

5.4.3异常处理

l重新抛出的异常必须保留原来的异常，即thrownewNewException（"message",

e）;而不能写成thrownewNewException（"message"）。

l在所有异常被捕获且没有重新抛出的地方必须写日志，避免异常的湮没。

l如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch

块。

l框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。

l多个异常应分别捕捉并处理，避免使用一个单一的catch来处理。

5.5JDK5.0及后续版本

l重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效

l不关心的warning信息用@SuppressWarnings（"unused"），@SuppressWarnings（"unchecked"）,@SuppressWarnings（"serial"）注释掉。

5.6性能与安全

5.6.1String与StringBugffer

不要使用如下String初始化方法：

Stringstr=newString（“abcdef”）;

这将产生两个对象，应当直接赋值：

Stringstr=“abcdef”;

在处理可变String的时候要尽量使用StringBuffer类，StringBuffer类是构成String类的基础。

String类将StringBuffer类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。

当我们在构造字符串的时候，我们应该用StringBuffer来实现大部分的工作，当工作完成后将StringBuffer对象再转换为需要的String对象。

比如：

如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用StringBuffer对象和她的append（）方法。

如果我们用String对象代替StringBuffer对象的话，将会花费许多不必要的创建和释放对象的CPU时间。

5.6.2集合

避免使用Vector和HashTable等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。

在新的系统设计中不当出现这些实现，使用ArrayList代替Vector，使用HashMap代替HashTable。

若却是需要使用同步集合类，当使用如下方式获得同步集合实例：

Mapmap=Collections.synchronizedMap（newHashMap（））;

由于数组、ArrayList与Vector之间的性能差异巨大（具体参见《Javafitball》），故在能使用数组时不要使用ArrayList，尽量避免使用Vector。

5.6.3对象

l避免在循环中频繁构建和释放对象。

l不再使用的对象应及时销毁。

l如无必要，不要序列化对象

5.6.4同步

l在不需要同步操作时避免使用同步操作类，如能使用ArrayList时不要使用

Vector。

l尽量少用同步方法，避免使用太多的synchronized关键字。

l尽量将同步最小化，即将同步作用到最需要的地方，避免大块的同步块或方法

等。

5.6.5final

●将参数或方法声明成final可提高程序响应效率，故此：

●注意绝对不要仅因为性能而将类、方法等声明成final，声明成final的类、方法一定要确信不再被继承或重载！

●不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成final。

●所有方法参数声明成final。

●私有（private）方法不需要声明成final。

●若方法确定不会被继承，则声明成final。

5.6.6垃圾收集和资源释放

不要过分依赖JVM的垃圾收集机制，因为你无法预测和知道JVM在什么时候运行GC。

尽可能早的释放资源，不再使用的资源请立即释放。

可能有异常的操作时必须在try的finally块中释放资源，如数据库连接、IO操

作等。

6自动代码检查和修正

6.1为了编码的一致性，统一将Workspace中的编码方式设置为UTF-8编码

6.2使用统一的代码模板

首先，需要加载指定的代码模板，打开CodeTemplates后选择Comments，再点击Import，将jsecode_eclipse_codetemplates.xml模板导入。

其次，在创建类或者接口的时候需要勾选Generatecomments

代码模板导入之后，请修改注释中的作者部分，改写为您自己的联系方式和名称。