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

Java 编码规范 第 1 页 共 31 页 JavaJava 编码规范编码规范 20092009 年年 6 6 月月 Java 编码规范 第 2 页 共 31 页 文档修订记录文档修订记录 章节章节 编号编号 章节名称章节名称修订内容简述修订内容简述修订日期修订日期修订前修订前 版本号版本号 建立文档2009-06-261.0 2.4 日志规范补充2009-07-131.0 2.6.4 异常规范25新增2009-07-151.0 2.6.5 工程配置文件规范新增2009-07-161.0 Java 编码规范 信息技术管理部第 3 页 共 31 页 1引言引言.5 1.1文档目的.5 1.2本规范的指导意义.5 1.3文档预期读者.5 1.4文档适用范围.5 1.5参考文档.5 2JAVA 代码开发规范代码开发规范.6 2.1命名规范.6 2.1.1文件 File .6 2.1.2包 Package6 2.1.3接口 Interface 6 2.1.4类 Class.7 2.1.5方法 Method.7 2.1.6参数 Parameter .8 2.1.7变量 Variable8 2.1.8实例变量 Instance Variable .9 2.1.9常量 Constant .9 2.1.10数组 Array9 2.2格式规范.10 2.2.1版权信息 Copyright Information.10 2.2.2注释 Comment10 2.2.3缩进 Indentation .12 2.2.4空格 Space12 2.2.5空行 Blank Line12 2.2.6行长度 Line Length13 2.2.7换行 New Line13 2.2.8圆括号 Parentheses.14 2.2.9大括号 Big Brackets.14 2.3语句规范.15 2.3.1变量、常量的使用15 2.3.2简单语句 Simple Statement.15 2.3.3条件语句 Condition Statement.16 2.3.4分支语句 Switch Statement .16 2.3.5循环语句 Loop Statement17 2.3.6包和引入语句 Packet and Import Statement.18 2.3.7声明语句 Declare Statement18 2.3.8例外控制语句 Exception Control Statement.19 2.3.9类和接口 Class and Interface.19 2.3.10构造/析构 Constructor/Finalizer20 2.3.11方法 Method.20 2.3.12属性 Attribute.22 2.3.13SQL 语句 SQL Statement 23 2.4日志规范.24 Java 编码规范 信息技术管理部第 4 页 共 31 页 2.5一般性规范.25 2.6其它代码开发规范.26 2.6.1多线程 Multi-Threading.26 2.6.2Servlet26 2.6.3JDBC27 2.6.4异常规范28 2.6.5工程配置文件规范29 Java 编码规范 信息技术管理部第 5 页 共 31 页 1 引言引言 1.1 文档目的文档目的 制定这个规范的目的是为了增加代码的可读性，使项目的所有代码具有统 一的编码风格，减少人员变动造成的损失，提高软件开发团队的生产效率，有 利于相关项目（票据集中提入、批量代收付、影像采集、前后台分离）向营运 平台整合。 1.21.2 前提前提与局限与局限 “深化前后台业务分离项目”的开发，以 eclips 为集成开发环境，以 java 为开发语言，以 weblogic 为 web 服务器，数据库类型为 oracle。本规范 的制定以此为前提，项目的开发应在此规范制定的原则下进行。 此规范具有相对合理性，不排除在特定场合下的局限性。 1.31.3 本规范的指导意义本规范的指导意义 1、提高软件的可读性，便于开发、维护人员理解代码； 2、减少软件的维护成本，有助于代码的修改、调试； 3、增加代码的复用程度，提高团队的合作效率； 4、养成好的编码习惯，形成严谨的思维模式； 5、增强程序的健壮性，降低错误的发生概率，提高运行性能。 1.4 文档预期读者文档预期读者 本文档的预期读者包括 J2EE 项目开发组全体成员：技术管理人员、系统设 计人员、系统开发人员、系统测试人员、系统维护人员、推广培训人员及其他 相关人员。 1.5 文档适用文档适用范围范围 本文档用于规范“深化前后台业务分离项目”的编码，也可供其他项目开 发人员参考。 Java 编码规范 信息技术管理部第 6 页 共 31 页 1.61.6 参考文档参考文档 Java 编码规范作者：建总行信息技术部 Java 编码规范 信息技术管理部第 7 页 共 31 页 2 Java 代码开发规范代码开发规范 2.1 命名规范命名规范 总体原则：命名应易于理解，能够见名识意。 2.1.1 普通普通文件文件 File NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 文件名命名方法, 单词 首字母小写开头 必须 thisIsTest.java 备注：备注： 2.1.2 包包 Package NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 采用建行 Internet 域 名格式命名，不得以个 人名字命名 必须 com.ccb.cos.package Package 名称小写必须 Package 名称必须为单 数 必须使用使用: : com.ccb.cos.servlet 不使用不使用: : com.ccb.cos.servlets 备注备注：建行标准建行标准 InternetInternet 域名为 ,所以包结构以 com.ccb 为前缀 2.1.3 接口接口 Interface NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 英语单词字头大写,其 他可以用大写或小写 必须 ThisIsAnInterfaceName 接口要 I 开头必须 ISomeInterface 备注备注： Java 编码规范 信息技术管理部第 8 页 共 31 页 2.1.4 类类 Class NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 英语单词字头大写,其 他可以用大写或小写 必须 ThisIsAClassName 自定义的异常类，应以 Exception 为后缀 必须 public class FtpException extends Exception 备注备注： 2.1.5 方法方法 Method NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 第一个英文单词首字母 小写 必须 openAccount() getString() 类的获取方法的方法名 采用被访问的字段名前 加上前缀 get 必须 getFirstName() getLastName() 类的设置方法的方法名 采用被访问的字段名前 加上前缀 set 必须 setFirstName() setLastName() 类的布尔型的判断方法 要求方法名使用单词 is 做前缀或者使用具 有逻辑意义的单词 必须 isPersistent() isString() equal() equals() 类的普通方法采用完整 的英文描述说明成员方 法功能，并尽可能是动 +名形式。 必须 openFile() addAccount() 如果可能，方法名、参 数名与要赋值的字段有 类似的名字 建议 setSize(int size) this.size = size; 用于转换的方法,名称以 “to”为前缀 建议 public SerBuf toSerBuf(); 防止多个方法修改同一变 量。应该只有一个方法能 写，其他只能读。 建议不建议： setSize(int size) this.size = size; doubleSize(int size) Java 编码规范 信息技术管理部第 9 页 共 31 页 this.size = size * 2; 备注备注： 2.1.6 参数参数 Parameter NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 参数的名字必须必须和变量 的命名规范一致 必须 thisAClassParameter 使用有意义的参数命名， 如果可能的话，使用和 要赋值的字段一样的名 字 建议 setCounter(int size) this.size=size; 备注备注： 2.1.7 变量变量 Variable NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 变量的名字必须必须以一个 小写字母开头，后面的 单词用大写字母开头 必须 username thisIsAClassVariable 循环记数变量通常采用 i, j, k 或者 counter 建议 i, j, k counter 异常变量以“e”开始必须 catch (Exception1 e1) 防止局部变量与公共变 量同名 必须 class Demo int i; /外部变量 . int func() int i; /局部变量 . 避免使用类似的名字， 或者仅仅是大小写不同 的名字 必须不建议： float PI, pi; /仅大小写 不同 float sales, salesSum; /名 称包含 同一项目中不同文件之必须不建议： Java 编码规范 信息技术管理部第 10 页 共 31 页 间、同一文件的前后之 间，表示相同意义的变 量，命名具有一致性 部位:String userName; / 操作员名称 部位 2:String operatorName; /操作员名称 建议：要么全部用 userName，要 么全部用 operatorName 备注备注： 对于使用 O/R 映射、开发工具自动生成变量等时，可以不采用本节要求的 变量命名规范 2.1.8 实例变量实例变量 Instance Variable NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 变量的名字必须必须以一个 小写字母开头，后面的 单词用大写字母开头 必须 username thisAClassInstance 备注备注： 2.1.9 常量常量 Constant NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 常量的名字必须必须都大写， 下划线分隔 必须 final static int DEFAULT_HTTP_PORT=80 备注备注： 2.1.10 数组数组 Array NamingNaming ConventionConvention 命名规范命名规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 数组的名字必须必须参照示 例命名 必须使用：使用： byte buffer 不使用：不使用： byte buffer 备注备注： Java 编码规范 信息技术管理部第 11 页 共 31 页 2.2 格式规范格式规范 2.2.1 版权信息版权信息 Copyright Information FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 版权信息必须必须位于 Java 文件的开头 必须/* * Copyright 2000 Shanghai XXX Co. Ltd. * All right reserved. */ 备注备注： 2.2.2 注释注释 Comment FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 类/接口注释： 描述 Java 类、接口、 每个文档注释设在注释 分割符/*/中，这 种注释应该放在声明之 前， “作者”如果使用 为建行员工，采用中文 名称加建行内部统一邮 箱作为标识；若为外部 人员，则使用中文名称 加公司邮箱作为标识。 版本中必须包含编写/ 最新修订日期 必须 /* * 功能/模块 ： * author 李广 liguang/zh/ccb * version 1.0 yyyy/mm/dd * 类描述 * 修订历史： * 日期 作者 参考 描述 * see 相关类连接 * 中国建设银行版权所有. */ public class Example 方法注释 描述方法。每个文档注 释设在注释分割符 /*/中，必须明确 的描述方法的出入参数、 异常、以及方法的含义。 对于实现接口的方法， 其注释的内容信息不得 少于原接口中的注释内 容 必须 /* * param * return *方法描述 */ Java 编码规范 信息技术管理部第 12 页 共 31 页 成员注释 所有类成员必须进行注 释；其中公共成员必须 进行 javaDoc 注释； 对于方法内部的私有成 员，缺省的需要注释, 对于临时的，直观含义 明确的可以不加注释； 必须 块注释： 块注释用于给文 件、方法、数据结构和 算法提供描述。必须利 用块注释描述程序的要 点。写在函数或方法中 的块注释必须与它所描 述的代码的缩进一致。 一个块注释之前应该由 一个空行将它与代码隔 离开 必须 /* * 在这里描述 */ 单行注释： 单行的短注释与它所跟 着的代码的缩进一致。 如果一个注释不能在一 行中写完，就应该使用 块注释的格式。单行注 释之前应该有一个空行。 必须 if (condition) / 当帐户是在 使用/* */临时删除原 代码 建议 备注备注： 注释要简单明了。 编写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一 致性。 在必要的地方注释，注释量要适中。注释的内容要清楚、明了，含义准确， 防止注释二义性。保持注释与其描述的代码相邻，即注释的就近原则。 对代码的注释应放在其上方相邻位置，不可放在下面。对数据结构的注释 应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释应放在 此域的右方；同一结构中不同域的注释要对齐。 变量、常量的注释应放在其上方相邻位置或右方。 全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程 存取它以及存取时注意事项等的说明。 在每个函数或过程的前面要有必要的注释信息，包括：函数或过程名称； Java 编码规范 信息技术管理部第 13 页 共 31 页 功能描述；输入、输出及返回值说明；调用关系及被调用关系说明等。 2.2.3 缩进缩进 Indentation FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 子功能块应在其父功能 块后缩进 必须 使用一个缩进位作为缩 进的单元 建议 if () SomeProcess(); 备注备注： 2.2.4 空空格格 Space FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 操作符前后使用空格建议 if (x = 3) 关键字与紧跟着的括号 间使用空格分开 建议 while (true) . for 语句中的表达式建 议使用空格分开 建议 for (expr1; expr2; expr3) 备注备注： 空格不应该置于方法名与其左括号之间，这将有助于区分关键字和方法调 用。 2.2.5 空行空行 Blank Line FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 两个方法之间使用一个 空行 建议 方法内的局部变量和方 法的第一条语句之间使 用一个空行 建议 块注释或单行注释之前 使用一个空行 建议 一个方法内的两个逻辑 段之间使用一个空行， 建议 Java 编码规范 信息技术管理部第 14 页 共 31 页 用以提高可读性 备注：备注： 空行将逻辑相关的代码段分隔开，以提高可读性。 2.2.6 行长度行长度 Line Length FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 单个方法的代码行(不 包含注释行)建议少于 100 行 建议 单个类的代码行(包含 注释行) 建议少于 1500 行 建议 一行的长度尽量少于 100 个字符，因为很多 的终端和工具不能很好 的处理，可能导致无法 正确显示 建议 备注：备注： 在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行。一条 语句折行后， 应该缩进一个缩进位。 2.2.7 换行换行 New Line FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 else if和 else 不要不要另起一行 catch需要另起一行 建议 if () else if () try catch(Exception e) 备注：备注： Java 编码规范 信息技术管理部第 15 页 共 31 页 2.2.8 圆括号圆括号 Parentheses FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 不应该不应该在语句中使用无 意义的括号 必须使用使用： if (i = 42) 不使用不使用： if(i) = 42) 左右括号与内部字符之 间不建议不建议出现空格 建议建议建议： callProc(aParameter) 不建议不建议： callProc( aParameter ) 方法名与紧跟的括号之 间不建议不建议出现空格 建议建议建议： callProc(aParameter) 不建议不建议： callProc (aParameter) 备注备注： 2.2.9 大括号大括号 Big Brackets FormatFormat SpecificationSpecification 格式规范格式规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 中的语句应该应该单独作 为一行 必须使用使用： if(i0) i+; 不使用不使用： if(i0) i+; 在使用时，左括号在 代码块起始行行尾，右 括号与代码块起始行上 下对齐。大括号里的代 码缩进一个缩进位。 必须 if(submit=null) clear(); else update(); 备注备注： Java 编码规范 信息技术管理部第 16 页 共 31 页 2.3 语句规范语句规范 2.3.1 变量、常量的使用变量、常量的使用 SpecificationSpecification 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 一个变量不要存在多个 用途 必须s = 账号； . s = 流水号; 变量类型应合适必须不建议: int salesSum; 建议： float salesSum; 操作变量时，应考虑变 量精度与类型转换 必须不建议： if (i = salesSum) if (1.2 = saleSum) 变量的作用域尽可能小。 作用域过大可能导致不 可预知的结果 建议 尽量使用常量的符号必须建议： errCode = SQL_NOT_FOUND; 不建议: errCode = 1403; 备注：备注： 2.3.2 简单语句简单语句 Simple Statement SpecificationSpecification 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 每一行只能只能包含一个语 句 必须使用使用： argv+; / 正确 argc-; / 正确 不使用不使用： argv+; argc-; 不要使用难懂的、技巧 性很高的语句 k = k+ + k+; 备注：备注： Java 编码规范 信息技术管理部第 17 页 共 31 页 2.3.3 条件语句条件语句 Condition Statement SpecificationSpecification 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 不要不要在条件语句内用 =, 这会与”=”混 乱(同时适用于 while 语句内条件说明) 必须不建议不建议: if (a = b) = c) 在混合运算表达式中使 用括号避免运算优先级 问题，即使对运算的优 先顺序非常清晰，也应 该这么做。(同时适用 于 while 语句内条件说 明) 建议建议建议: if (a = b) else /对应哪个 if ? k = 2; 不要将赋值与判断放在 一个语句里 必须不建议： if (file = fopen(“a.txt”) = NULL) 备注：备注： 2.3.4 分支语句分支语句 Switch Statement SpecificationSpecification 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 每一个 Switch 的 case 建议有 default 做为最 后出口 建议 switch (x) case 1 : expr;break;break; / end case case 2 : expr;break;break; / end case default : expr;break;break; / end default Java 编码规范 信息技术管理部第 18 页 共 31 页 / end switch 从一个 case 进入另一 个 case 时，必须明确 注明 必须 switch (x) case 1 : expr1; /注意：x=1 时,需继续执 行 expr2 case 2 : expr2; break;break; default: exprN; break;break; / end switch 备注备注： 2.3.5 循环语句循环语句 Loop Statement SpecificationSpecification 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 如果 for 循环中表达式 很长，建议将多行进行 分割，提高代码的可读 性 建议 for 语句的初始化或更 新语句中使用逗号时， 避免复杂性，最多使用 三个变量。必要的话， 初始化可以在 for 循环 之前使用单独的语句， 或更新语句可以在循环 的底部执行 建议 在多重循环中，应将最 长的循环放在最内层， 最短的循环放在最外层， 以减少 CPU 跨切循环层 的次数 建议 for (i=1; i= 0) for (i=0; i.log 的命名规 则。文件大小限制为最 多 20Mb，即当日志文 件超过 20Mb 时，旧日 志文件重命名为.log.n(n 从 1 开始 编号以步长 1 递增)， 新日志写入 .log 必须 日志的输出格式(不包 括异常树信息)： 日期(yyyy-M-d) 时间 (HH:mm:ss) 日志级别 (对应程序文件名:行号) 定制信息 必须 对于“敏感”信息（如 客户密码） ，禁止使用 debug 以上级别的日志 记录 必须 日志应应区分如下几类情 形： 发生致命错误时运 行将终止(fatal) 发生错误 仍可继 续执行(error) 发生警告仍可继续 执行(warn) 记录运行过程或干 预情况(info) 调试程序记录信息 必须 Java 编码规范 信息技术管理部第 26 页 共 31 页 等(debug) 备注：备注： 统一使用类库中记录日志接口实现日志记录、信息打印功能。有关日志分 类及规范要求参见中心相关日志规范，本处仅给出共性原则。 2.5 一般性规范一般性规范 CateloCatelo g g 类别类别 GenericGeneric StandardStandard 一般性规范一般性规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 排序 import 语句， 越具体的包或者 类越往后排 建议 import java.io.*; import java.text.*; import java.util.*; import javax.servlet.*; import java.servlet.tcp.*; import com.ibm.gui.some.*; import com.ibm.gui.test.*; Import 相关问 题 如果只用到某一 个包中某一个类 的话，尽量 import 这一个具 体的类，而不是 整个包 建议 java.io.IOException; import java.text.Format; import java.util.Vector; Generi c 一般 问题 一个缩进位相当 于 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 不推 建议 Java 编码规范 信息技术管理部第 27 页 共 31 页 荐的 HashTable 和 Vector 进行字符串连接 的时候，尽量使 用 StringBuffer 类来进行类似处 理 建议建议建议：StringBuffer strBuf = new StringBuffer(“Name is ”); return strBuf.toString(); or : return new StringBuffer(“Name is ”).t oString(); 不建议不建议：return “Name is ”; 备注：备注： 2.6 其它其它代码开发规范代码开发规范 2.6.1 多线程多线程 Multi-Threading StandardStandard 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 建议不要建议不要使用 Java2 不推荐使用的 相关方法 必须不建议不建议: Suspend(); Resume(); Stop(); 尽量同步最小的逻辑单元，比如 Synchronize 程序块而不是整个方 法 建议 尽量避免尽量避免在同步的模块中进行 I/O 等速度慢的系统调用以免影响性能 建议 备注：备注： 2.6.2 Servlet StandardStandard 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 Java 编码规范 信息技术管理部第 28 页 共 31 页 Servlet 类命名： 一般对应于所服务的对象加后缀 Servlet 来命名 必须 UserServlet TradeServlet 使用 servlet 注意共享变量的同步 问题，尽量使用 servlet 的局部变 量 建议 避免避免在 HttpSession 中放置大对象 以免影响 Session 性能 建议 备注：备注： 2.6.3 JDBC StandardStandard 规范规范 MustMust FollowFollow oror NotNot 是否必须遵循是否必须遵循 ExampleExample 范例范例 把 Connection/Statement/ ResultSet 关闭语句都写 在一起在 Finally 中进 行关闭处理 建议 try / get JDBC connection and perform JDBC catch (Throwable t) finally if (null != resultSet) try resultSet.close(); catch (Throwable t) if (null != statement) try statement.close(); catch (Throwable t) if (null != connection) try connection.close(); catch (Throwable t) 建议使用字段名来调用 数据库中间层组件返回 的结果集。这样在数据 库设计更改或查询的SQL 语句发生变化时，不会 影响到程序的执行。 建议建议：建议： 用字段名来存取结果集 for(inti=1;i=dt.getRowCoun t();i+) String field1 = dt.getField(i,“field1“). toString(); 不建议：不建议： for(int Java 编码规范 信息技术管理部第 29 页 共 31 页 i=1;i