编码规范培训-Java编码规范.doc

《编码规范培训-Java编码规范.doc》由会员分享，可在线阅读，更多相关《编码规范培训-Java编码规范.doc（31页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、Java编码规范2009年6月文档修订记录章节编号章节名称修订内容简述修订日期修订前版本号建立文档2009-06-261.02.4日志规范补充2009-07-131.02.6.4 异常规范25新增2009-07-151.02.6.5工程配置文件规范新增2009-07-161.01引言51.1文档目的51.2本规范的指导意义51.3文档预期读者51.4文档适用范围51.5参考文档52JAVA代码开发规范62.1命名规范62.1.1文件 File62.1.2包 Package62.1.3接口Interface62.1.4类 Class72.1.5方法 Method72.1.6参数 Paramete

2、r82.1.7变量 Variable82.1.8实例变量 Instance Variable92.1.9常量 Constant92.1.10数组 Array92.2格式规范102.2.1版权信息 Copyright Information102.2.2注释 Comment102.2.3缩进 Indentation122.2.4空格 Space122.2.5空行 Blank Line122.2.6行长度 Line Length132.2.7换行 New Line132.2.8圆括号 Parentheses142.2.9大括号 Big Brackets142.3语句规范152.3.1变量、常量的使

3、用152.3.2简单语句 Simple Statement152.3.3条件语句 Condition Statement162.3.4分支语句 Switch Statement162.3.5循环语句 Loop Statement172.3.6包和引入语句 Packet and Import Statement182.3.7声明语句 Declare Statement182.3.8例外控制语句 Exception Control Statement192.3.9类和接口 Class and Interface192.3.10构造/析构 Constructor/Finalizer202.3.11方

4、法 Method202.3.12属性 Attribute222.3.13SQL语句 SQL Statement232.4日志规范242.5一般性规范252.6其它代码开发规范262.6.1多线程 Multi-Threading262.6.2Servlet262.6.3JDBC272.6.4异常规范282.6.5工程配置文件规范291 引言1.1 文档目的制定这个规范的目的是为了增加代码的可读性，使项目的所有代码具有统一的编码风格，减少人员变动造成的损失，提高软件开发团队的生产效率，有利于相关项目（票据集中提入、批量代收付、影像采集、前后台分离）向营运平台整合。1.2 前提与局限“深化前后台业务

5、分离项目”的开发，以eclips为集成开发环境，以java为开发语言，以weblogic为web 服务器，数据库类型为oracle。本规范的制定以此为前提，项目的开发应在此规范制定的原则下进行。此规范具有相对合理性，不排除在特定场合下的局限性。1.3 本规范的指导意义1、提高软件的可读性，便于开发、维护人员理解代码；2、减少软件的维护成本，有助于代码的修改、调试；3、增加代码的复用程度，提高团队的合作效率；4、养成好的编码习惯，形成严谨的思维模式；5、增强程序的健壮性，降低错误的发生概率，提高运行性能。1.4 文档预期读者本文档的预期读者包括J2EE项目开发组全体成员：技术管理人员、系统设计人

6、员、系统开发人员、系统测试人员、系统维护人员、推广培训人员及其他相关人员。1.5 文档适用范围本文档用于规范“深化前后台业务分离项目”的编码，也可供其他项目开发人员参考。1.6 参考文档Java编码规范作者：建总行信息技术部2 Java代码开发规范2.1 命名规范总体原则：命名应易于理解，能够见名识意。2.1.1 普通文件 FileNaming Convention命名规范Must Follow or Not是否必须遵循Example 范例文件名命名方法, 单词首字母小写开头必须thisIsTest.java备注：2.1.2 包 PackageNaming Convention命名规范Must

7、 Follow or Not是否必须遵循Example 范例采用建行Internet域名格式命名，不得以个人名字命名必须com.ccb.cos.packagePackage名称小写必须Package名称必须为单数必须使用:com.ccb.cos.servlet不使用:com.ccb.cos.servlets备注：建行标准Internet域名为 ,所以包结构以com.ccb为前缀2.1.3 接口InterfaceNaming Convention命名规范Must Follow or Not是否必须遵循Example范例英语单词字头大写,其他可以用大写或小写必须ThisIsAnInterfaceN

8、ame接口要I开头必须ISomeInterface备注：2.1.4 类 ClassNaming Convention命名规范Must Follow or Not是否必须遵循Example范例英语单词字头大写,其他可以用大写或小写必须ThisIsAClassName自定义的异常类，应以Exception为后缀必须public class FtpException extends Exception备注：2.1.5 方法 MethodNaming Convention命名规范Must Follow or Not是否必须遵循Example范例第一个英文单词首字母小写必须openAccount()ge

9、tString()类的获取方法的方法名采用被访问的字段名前加上前缀get必须getFirstName()getLastName()类的设置方法的方法名采用被访问的字段名前加上前缀set必须setFirstName()setLastName()类的布尔型的判断方法要求方法名使用单词 is 做前缀或者使用具有逻辑意义的单词必须isPersistent()isString()equal()equals()类的普通方法采用完整的英文描述说明成员方法功能，并尽可能是动+名形式。 必须openFile()addAccount()如果可能，方法名、参数名与要赋值的字段有类似的名字建议setSize(int

10、size) this.size = size; 用于转换的方法,名称以“to”为前缀建议public SerBuf toSerBuf();防止多个方法修改同一变量。应该只有一个方法能写，其他只能读。建议不建议：setSize(int size) this.size = size; doubleSize(int size) this.size = size * 2; 备注：2.1.6 参数 Parameter Naming Convention命名规范Must Follow or Not是否必须遵循Example范例参数的名字必须和变量的命名规范一致必须thisAClassParameter使用

11、有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字建议setCounter(int size)this.size=size;备注：2.1.7 变量 VariableNaming Convention命名规范Must Follow or Not是否必须遵循Example范例变量的名字必须以一个小写字母开头，后面的单词用大写字母开头必须usernamethisIsAClassVariable循环记数变量通常采用i, j, k或者counter建议i, j, kcounter异常变量以“e”开始必须catch (Exception1 e1)防止局部变量与公共变量同名必须class Demo

12、int i; /外部变量.int func() int i; /局部变量 .避免使用类似的名字，或者仅仅是大小写不同的名字必须不建议：float PI, pi; /仅大小写不同float sales, salesSum; /名称包含同一项目中不同文件之间、同一文件的前后之间，表示相同意义的变量，命名具有一致性必须不建议：部位:String userName; /操作员名称部位2:String operatorName; /操作员名称建议：要么全部用userName，要么全部用operatorName备注：l 对于使用O/R映射、开发工具自动生成变量等时，可以不采用本节要求的变量命名规范2.1.

13、8 实例变量 Instance VariableNaming Convention命名规范Must Follow or Not是否必须遵循Example范例变量的名字必须以一个小写字母开头，后面的单词用大写字母开头必须usernamethisAClassInstance备注：2.1.9 常量 ConstantNaming Convention命名规范Must Follow or Not是否必须遵循Example范例常量的名字必须都大写，下划线分隔必须final static int DEFAULT_HTTP_PORT=80备注：2.1.10 数组 ArrayNaming Convention命

14、名规范Must Follow or Not是否必须遵循Example范例数组的名字必须参照示例命名必须使用：byte buffer不使用：byte buffer备注：2.2 格式规范2.2.1 版权信息 Copyright Information Format Specification格式规范Must Follow or Not是否必须遵循Example范例版权信息必须位于Java文件的开头必须/* * Copyright 2000 Shanghai XXX Co. Ltd. * All right reserved. */备注：2.2.2 注释 Comment Format Specifi

15、cation格式规范Must Follow or Not是否必须遵循Example范例类/接口注释：描述Java类、接口、每个文档注释设在注释分割符/*/中，这种注释应该放在声明之前，“作者”如果使用为建行员工，采用中文名称加建行内部统一邮箱作为标识；若为外部人员，则使用中文名称加公司邮箱作为标识。版本中必须包含编写/最新修订日期必须/* 功能/模块 ：* author 李广liguang/zh/ccb* version 1.0 yyyy/mm/dd* 类描述 * 修订历史：* 日期 作者 参考 描述* see 相关类连接* 中国建设银行版权所有.*/public class Example

16、方法注释描述方法。每个文档注释设在注释分割符/*/中，必须明确的描述方法的出入参数、异常、以及方法的含义。对于实现接口的方法，其注释的内容信息不得少于原接口中的注释内容必须/* param * return*方法描述*/成员注释所有类成员必须进行注释；其中公共成员必须进行javaDoc注释；对于方法内部的私有成员，缺省的需要注释,对于临时的，直观含义明确的可以不加注释；必须块注释：块注释用于给文件、方法、数据结构和算法提供描述。必须利用块注释描述程序的要点。写在函数或方法中的块注释必须与它所描述的代码的缩进一致。一个块注释之前应该由一个空行将它与代码隔离开必须/* * 在这里描述*/单行注释：

17、单行的短注释与它所跟着的代码的缩进一致。如果一个注释不能在一行中写完，就应该使用块注释的格式。单行注释之前应该有一个空行。必须if (condition) / 当帐户是在 使用/* */临时删除原代码建议备注：l 注释要简单明了。l 编写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。l 在必要的地方注释，注释量要适中。注释的内容要清楚、明了，含义准确，防止注释二义性。保持注释与其描述的代码相邻，即注释的就近原则。l 对代码的注释应放在其上方相邻位置，不可放在下面。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释应放在此域的右方；同一结构中不同域的注

18、释要对齐。l 变量、常量的注释应放在其上方相邻位置或右方。l 全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。l 在每个函数或过程的前面要有必要的注释信息，包括：函数或过程名称；功能描述；输入、输出及返回值说明；调用关系及被调用关系说明等。2.2.3 缩进 Indentation Format Specification格式规范Must Follow or Not是否必须遵循Example范例子功能块应在其父功能块后缩进必须使用一个缩进位作为缩进的单元建议if ()SomeProcess();备注：2.2.4 空格 Space Format S

19、pecification格式规范Must Follow or Not是否必须遵循Example范例操作符前后使用空格建议if (x = 3) 关键字与紧跟着的括号间使用空格分开建议while (true) .for语句中的表达式建议使用空格分开建议for (expr1; expr2; expr3)备注：l 空格不应该置于方法名与其左括号之间，这将有助于区分关键字和方法调用。2.2.5 空行 Blank Line Format Specification格式规范Must Follow or Not是否必须遵循Example范例两个方法之间使用一个空行建议方法内的局部变量和方法的第一条语句之间使用

20、一个空行建议块注释或单行注释之前使用一个空行建议一个方法内的两个逻辑段之间使用一个空行，用以提高可读性建议备注：l 空行将逻辑相关的代码段分隔开，以提高可读性。2.2.6 行长度 Line Length Format Specification格式规范Must Follow or Not是否必须遵循Example范例单个方法的代码行(不包含注释行)建议少于100行建议 单个类的代码行(包含注释行) 建议少于1500行建议一行的长度尽量少于100个字符，因为很多的终端和工具不能很好的处理，可能导致无法正确显示建议备注：l 在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行。一条语句折行

21、后， 应该缩进一个缩进位。2.2.7 换行 New Line Format Specification格式规范Must Follow or Not是否必须遵循Example范例else if和 else不要另起一行catch需要另起一行建议if () else if () trycatch(Exception e)备注：2.2.8 圆括号 Parentheses Format Specification格式规范Must Follow or Not是否必须遵循Example范例不应该在语句中使用无意义的括号必须使用：if (i = 42)不使用：if(i) = 42)左右括号与内部字符之间不建议

22、出现空格建议建议：callProc(aParameter)不建议：callProc( aParameter )方法名与紧跟的括号之间不建议出现空格建议建议：callProc(aParameter)不建议：callProc(aParameter)备注：2.2.9 大括号 Big BracketsFormat Specification格式规范Must Follow or Not是否必须遵循Example范例中的语句应该单独作为一行必须使用：if(i0) i+;不使用：if(i0) i+;在使用时，左括号在代码块起始行行尾，右括号与代码块起始行上下对齐。大括号里的代码缩进一个缩进位。必须if(su

23、bmit=null)clear();elseupdate();备注：2.3 语句规范2.3.1 变量、常量的使用Specification规范Must Follow or Not是否必须遵循Example范例一个变量不要存在多个用途必须s = 账号；.s = 流水号;变量类型应合适必须不建议:int salesSum;建议：float salesSum;操作变量时，应考虑变量精度与类型转换必须不建议：if (i = salesSum)if (1.2 = saleSum)变量的作用域尽可能小。作用域过大可能导致不可预知的结果建议尽量使用常量的符号必须建议：errCode = SQL_NOT_FO

24、UND;不建议:errCode = 1403;备注：2.3.2 简单语句 Simple Statement Specification规范Must Follow or Not是否必须遵循Example范例每一行只能包含一个语句必须使用：argv+; / 正确argc-; / 正确 不使用：argv+; argc-;不要使用难懂的、技巧性很高的语句k = k+ + k+;备注：2.3.3 条件语句 Condition Statement Specification规范Must Follow or Not是否必须遵循Example范例不要在条件语句内用=, 这会与”=”混乱(同时适用于while语

25、句内条件说明)必须不建议:if (a = b) = c)在混合运算表达式中使用括号避免运算优先级问题，即使对运算的优先顺序非常清晰，也应该这么做。(同时适用于while语句内条件说明)建议建议:if (a = b) & (c = d)不建议:If (a = b & c = d)嵌套语句时，应使用“”符号将内外层代码显式地分开必须不建议：if (1 = i)if (2 = j) k = 1;else /对应哪个if ? k = 2;不要将赋值与判断放在一个语句里必须不建议：if (file = fopen(“a.txt”) = NULL)备注：2.3.4 分支语句 Switch Statemen

26、t Specification规范Must Follow or Not是否必须遵循Example范例每一个Switch的case建议有default做为最后出口建议switch (x) case 1 : expr;break; / end casecase 2 : expr;break; / end casedefault : expr;break; / end default / end switch从一个case进入另一个case时，必须明确注明必须switch (x) case 1 : expr1;/注意：x=1时,需继续执行expr2case 2 : expr2;break;defau

27、lt: exprN;break; / end switch备注：2.3.5 循环语句 Loop Statement Specification规范Must Follow or Not是否必须遵循Example范例如果for循环中表达式很长，建议将多行进行分割，提高代码的可读性建议for语句的初始化或更新语句中使用逗号时，避免复杂性，最多使用三个变量。必要的话，初始化可以在for循环之前使用单独的语句，或更新语句可以在循环的底部执行建议在多重循环中，应将最长的循环放在最内层，最短的循环放在最外层，以减少CPU跨切循环层的次数建议for (i=1; i10; i+) for (j=1; j= 0)

28、for (i=0; i1000; i+) expr1elsefor (i=0; i1000; i+) expr2不要轻易在循环体内修改循环变量建议备注：2.3.6 包和引入语句 Packet and Import Statement Specification规范Must Follow or Not是否必须遵循Example范例import 中标准的包名要在本地的包名之前，。建议package .statsimport java.io.*;import java.util.Observable;import hotlava.util.Application;import语句建议遵循以下导入顺序

29、：1. jdk标准包2. java扩展包3. 使用外部库的包4. 使用建行的公共包5. 使用项目的公共包建议备注：l import语句尽量不使用通配符“*”(会加大程序编译时的开销和生成的类文件的大小)。l 为每个自身独立的项目和一组有关联的方法创建一个新的java包。2.3.7 声明语句 Declare Statement Specification规范Must Follow or Not是否必须遵循Example范例不要将不同类型变量的声明放在同一行。必须使用：int foo;int fooarray;不使用：int foo, fooarray;int i; String s;尽量在声明局

30、部变量的同时初始化。必须int i = 0;避免声明的局部变量与上一级变量重名。必须int count; . myMethod() if (condition) int count = 0; / AVOID! . . 备注：2.3.8 例外控制语句 Exception Control Statement Exception Control例外Must Follow or Not是否必须遵循Example范例不要有空的catch语句出现，至少打印出在哪里抛出例外和相关信息必须在捕获一场时尽可能使用具体异常，最好不要使用Exception这类通用异常类型，除非有明确的要求需要捕获所有异常。备注：2

31、.3.9 类和接口 Class and Interface Specification规范Must Follow or Not是否必须遵循Example范例类、接口定义之前应先进行注释。注释包括类、接口的目的、作用、功能，实现的算法、使用方法、示例程序等，还可以包括期望改进工作的地方和不希望改变的地方必须左括号”置于声明行尾，右括号”另起一行，缩进匹配相应开始语句必须class Sample int ivar1; int ivar2;Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() 备注：2.3.10 构造/析构 Cons

32、tructor/FinalizerSpecification规范Must Follow or Not是否必须遵循Example范例要初始化父类的构造函数建议不要在构造函数中初始化静态数据, 应在声明中初始化建议用构造函数做简单初始化, 复杂的功能应留到其他的方法在构造函数后执行建议使用Finalize()释放资源，不过不要完全依赖Finalize，资源要尽可能早的进行释放建议finalize() if (NotReleased() try releaseResource();catch (Throwable t) handleError();备注：2.3.11 方法 Method Specif

33、ication规范Must Follow or Not是否必须遵循Example范例对于参数合法性的检查，应事先明确到底是调用者检查，还是被调用的方法检查。要避免都不检查和都检查必须一个方法应仅完成一个功能，不要“顺便”做点其他的事。其他的事应有其他方法实现。必须尽可能缩小方法的能够被访问的范围。如果不需要类以外的方法访问的方法则使用private，而只需要package范围内访问的方法使用default，若即要package内的代码能够访问又要求其继承类能够访问则使用protected，最后若需要所有的代码都可以访问则再使用public建议应尽可能验证所有传入参数，不能假定非空对象, 验证有

34、错误时返回明确的错误信息建议If(Parameter1!=NULL)/ endIf if(Parameter2!=NULL) / endIf 尽量保证每个方法只有一个出口，否则可能出现丢失返回的情况。如果有分支，应保证每个分支都有返回值。建议boolean check() boolean result = false;if (.) result = true;return result;使用方法后，必须分析返回值建议ret = ccbsTx();if (ret != 0) .方法的参数不要过多，否则以对象的形式传入建议尽量不要编写依赖于其他方法的方法，降低方法的耦合度建议少用递归调用建议备注：

35、2.3.12 属性 Attribute Catelog类别Define Specification 定义规范Must Follow or Not是否必须遵循Example范例Constant 常量当某一些数据为常量时不要直接在代码中使用这些数据，而应该先将这些数据定义为Java的常量然后引用常量的标识符来完成预定义功能必须Parameters and Attribute在子类中不要重复定义父类中的成员变量必须建议使用getter和setter访问同一个类中的成员变量，或者用关键字this建议this.getInternalName();或者this.internalName;应避免出现publ

36、ic的成员变量，原则上都是private，用getter和setter进行访问，保证封装性建议Local Variable 临时变量避免内联(in-line)声明临时变量，除非是循环计数建议for (int i = 0; i 10; i+).建议不要在一个语句中为多个变量赋相同的值建议建议:fooBar.fChar =c;barFoo.lchar = c;不建议:fooBar.fChar = barFoo.lchar = c;不要把赋值号用在容易被误认为等号的地方建议赋值不要为了提高运行时的性能而使用嵌入式的赋值建议建议:a = b + c;d = a + r不建议:d = (a = b +

37、c) + r结构设计仔细设计各成员变量的顺序，尽量使最密切相关的成员或同数据类型的成员在一起，使类的结构容易理解、节省占用空间建议Class Demoint x1;int x2;.String s1;String s2;.2.3.13 SQL语句 SQL Statement Specification规范Must Follow or Not是否必须遵循Example范例SQL关键字应全部大写必须SELECT ename FROM emp表名和字段名应小写必须备注：2.4 日志规范Specification规范Must Follow or Not是否必须遵循Example范例在正式提交的代码中，

38、不允许使用Console输出方式显示信息必须日志文件名为.log的命名规则。文件大小限制为最多20Mb，即当日志文件超过20Mb时，旧日志文件重命名为.log.n(n从1开始编号以步长1递增)，新日志写入.log必须日志的输出格式(不包括异常树信息)：日期(yyyy-M-d) 时间(HH:mm:ss) 日志级别(对应程序文件名:行号)定制信息必须对于“敏感”信息（如客户密码），禁止使用debug以上级别的日志记录必须日志应区分如下几类情形：l 发生致命错误时运行将终止(fatal)l 发生错误 仍可继续执行(error)l 发生警告仍可继续执行(warn)l 记录运行过程或干预情况(info)

39、l 调试程序记录信息等(debug)必须备注：l 统一使用类库中记录日志接口实现日志记录、信息打印功能。有关日志分类及规范要求参见中心相关日志规范，本处仅给出共性原则。2.5 一般性规范Catelog 类别Generic Standard一般性规范Must Follow or Not是否必须遵循Example范例Import相关问题排序import语句，越具体的包或者类越往后排建议import java.io.*;import java.text.*;import java.util.*;import javax.servlet.*;import java.servlet.tcp.*;impo

40、rt com.ibm.gui.some.*;import com.ibm.gui.test.*;如果只用到某一个包中某一个类的话，尽量import这一个具体的类，而不是整个包建议java.io.IOException;import java.text.Format;import java.util.Vector;Generic一般问题一个缩进位相当于4个空格建议常量值应定义为有意义的类静态变量，建议加上final声明建议public static final String KEY_ADDRESS = Connection.Address;类中用this关键字来访问同一个类中的非静态方法或变量建议public void myFunction() this.amount = 0;int newAmount = this.getBalance();比较的时候要把常量放在操作符左边建议if (1 = x) and if (“123”.equals(userId)要使用Java2引入的Collection类，尽量不要再使用Java2不推荐的HashTable和Vector建议