社保核心平台三版本地化开发规范_JAVA编码

n 文档编号B11 RC C04 JB HXPT 04 版本号V1 0 发放号F01 受控状态受控 社会保险管理信息系统核心平台三版社会保险管理信息系统核心平台三版 本地化开发规范本地化开发规范 JAVAJAVA 编码规范编码规范 编制部门 社会保险管理信息系统核心平台三版项目组 编制人 技术支持组编制日期 2007 09 17 审核人 魏文麟审核日期 2007 09 24 批准人 批准日期 北京利博赛社保信息技术有限公司北京利博赛社保信息技术有限公司 社会保险管理信息系统核心平台三版本地化开发规范 第 1 页 文档修改历史 版本版本修改记录修改记录修改日期修改日期修改人修改人 社会保险管理信息系统核心平台三版本地化开发规范 第 2 页 目录目录 1JAVA 编码通用规则编码通用规则 3 2代码编写样式代码编写样式 5 2 1 JAVA 文件样式 5 2 2 声明 9 2 3 语句 11 2 4 缩进排版 16 2 5 空白 19 2 6 注释规范 20 3编程技巧编程技巧 22 4JAVA 性能优化性能优化 24 5数据库访问性能注意事项数据库访问性能注意事项 25 6程序兼容性注意事项程序兼容性注意事项 25 7HIBERNATE ORM 使用要点使用要点 26 社会保险管理信息系统核心平台三版本地化开发规范 第 3 页 1Java 编码通用规则编码通用规则 1 Java 源文件必须有 java 扩展名 2 Java 已编译的类文件必须有 class 扩展名 3 每个 Java 源文件包含一个单一的 public class 或 interface 当 private class 及 interface 与 public class 相关联时 可将它们放在同一个源文件 中作为 public class public class 应当是文件中的第一个 class 及 interface Java 源文件编写顺序 Beginning comments Package 及 Import statements Class 和 interface declarations 4 每行代码避免超过 100 个字符 5 当一个表达式在一行中写不下时 按如下规则换行 逗号 后断开 operator 前断开 新行中表达式的起点与前一行左对齐 如果上法使右边空余太少 可只缩进四个空格开始新行 6 在同一行中不要放不同的 types 7 最好在 declare local variables 的地方即做 local variables 的初始化 唯 一的例外是 如果初始值是先由其他计算得出的的时候 不在 declare 的地方做变量初始化 8 在同一个 inner block 中不要 declare 相同的变量名称 9 当编写 class 及 interface 时 须遵循下述的格式规则 在 a method name 和 开始的参数列表之间不能有空格 在 declaration statement 下面一行的起始处加 open 以 close 开始的行与 open 相匹配 当出现一个 null statement 时 之后紧跟 10 每行最多包括一个 statement 社会保险管理信息系统核心平台三版本地化开发规范 第 4 页 11 IF statements 使用 12 uniguq package 的前缀组成均为小写的 ASCII 字符 并且应是最上层的 域名之一 例如 com edu 等等 13 Class name 应该尽量是名词 第一个字母大写 全名大小写混合 Class name 应该简单 描述性强 避免使用缩写 14 Interface 的命名同 Class 15 Methods 应该是动词 第一个字母小写 每个中间单词的第一个字母大 写 16 除变量外 所有的 instance class 及 class constants 均是大小写混 写 第一个字母小写 中间单词的第一个字母大写 变量名称不能以下 划线 或 字符开头 变量名称应简短且语义清晰 避免出现只 有一个字符的变量名 17 Class constans 和 ANSI constants 类型的变量名称应全部大写 且字 母间用下划线 隔开 尽量避免使用 ANSI constants 以利于程序 诊断 18 不要随意将任何 instance 或 class 变量公有化 public 19 避免用一个 object 存取一个 class 静态 变量或 method 可使用一个 class name 代替 20 除了 1 0 和 1 可作为 for 循环中的计数器外 数字常数 文字形的 不应该直接编码 21 在一个 statement 中避免将多个变量赋同一个值 22 不要将赋值符号 assignment 放在易于等号 equality 混淆的地方 23 不要为了提高实时性能而使用 embedded assignments 社会保险管理信息系统核心平台三版本地化开发规范 第 5 页 2代码编写样式代码编写样式 2 1 JAVA 文件文件样式样式 一个文件由被空行分割而成的段落以及标识每个段落的可选注释组成 每个 Java 源文件都包含一个单一的公共类或接口 若私有类和接口与一个 公共类相关联 可以将它们和公共类放入同一个源文件 公共类必须是这 个文件中的第一个类或接口 Java 源文件按以下顺序布局 开头注释 包和引入语句 类和接口声明 超过 2000 行的程序难以阅读 应该尽量避免 开头注释开头注释 Beginning Beginning Comments Comments 所有的源文件都应该在开头有一个 C 语言风格的注释 其中列出类名 版 本信息 日期和版权声明 Classname Version information Date Copyright notice 包和引入语句包和引入语句 Package Package andand ImportImport Statements Statements 社会保险管理信息系统核心平台三版本地化开发规范 第 6 页 在多数 Java 源文件中 第一个非注释行是包语句 在它之后可以跟引入语 句 例如 package java awt import java awt peer CanvasPeer 类和接口声明类和接口声明 Class Class andand InterfaceInterface Declarations Declarations 下表描述了类和接口声明的各个部分以及它们出现的先后次序 表格 1 类与接口申明顺序 类 接口声明的各 部分 注解 1类 接口文档注释 该注释中所需包含的信息 参见文档注释 2类或接口的声明 3类 接口实现的注 释 如果 有必要的话 该注释应包含任何有关整个类或接口的信息 而这 些信息又不适合作为类 接口文档注释 4类的 静态 变量首先是类的公共变量 随后是保护变量 再后是包 一级别的变量 没有访问修饰符 access modifier 最后是私有变量 5实例变量首先是公共级别的 随后是保护级别的 再后是包 一级别的 没有访问修饰符 最后是私有级别的 6构造器 7方法这些方法应该按功能 而非作用域或访问权限 分 组 例如 一个私有的类方法可以置于两个公有的 实例方法之间 其目的是为了更便于阅读和理解代 码 社会保险管理信息系统核心平台三版本地化开发规范 第 7 页 核三核三 javajava 文件遵循的具体样式规则如下 文件遵循的具体样式规则如下 1 package imports package 行要在 import 行之前 import 中标准的包名要在本地的包名之 前 而且按照字母顺序排列 Classname Version information Date Copyright notice package mons import java util Calendar import java util Date import org apache log4j Logger 2 Class 接下来的是类的注释 一般是用来解释类的 提供有关日期的实用方法集 author LBS POC TEAM version 1 0 接下来是类定义 包含了在不同的行的 extends 和 implements public class DateUtil 3 Class Fields 接下来是类的成员变量 社会保险管理信息系统核心平台三版本地化开发规范 第 8 页 private String date public 的成员变量必须生成文档 JavaDoc proceted private 和 package 定义的成员变量如果名字含义明确的话 可以没有注释 4 存取方法 接下来是类变量的存取的方法 它只是简单的用来将类的变量赋值获取值 的话 可以简单的写在一行上 获取日期 return date 日期 public String getDate return date 设置日期 param date 日期 public void setDate String date this date date 5 构造函数 下来是构造函数 它应该用递增的方式写 比如 参数多的写在后面 访问类型 public private 等 和 任何 static final 或 synchronized 应该在一行中 并且方法和参数另写一行 这样可以使方法和 参数更易读 protected DateUtil 6 类方法 下面开始写类的方法 社会保险管理信息系统核心平台三版本地化开发规范 第 9 页 得到将 date 增加指定月数后的 date param date java util Date param intBetween 指定的月差距 return date 加上 intBetween 年数后的日期 public static Date increaseYear Date date int intBetween Calendar calo Calendar getInstance calo setTime date calo add Calendar YEAR intBetween return calo getTime 7 main 方法 如果 main String 方法已经定义了 那么它应该写在类的最底部 测试方法 param args 参数 public static void main String args 2 2 声明声明 推荐一行一个声明 因为这样以利于写注释 亦即 int level indentation level int size size of table 社会保险管理信息系统核心平台三版本地化开发规范 第 10 页 不要将不同类型变量的声明放在同一行 例如 int foo fooarray WRONG 尽量在声明局部变量的同时初始化 唯一不这么做的理由是变量的初始值 依赖于某些先前发生的计算 只在代码块的开始处声明变量 一个块是指任何被包含在大括号 和 中间的代码 不要在首次用到该变量时才声明之 这会把注意力不集中 的程序员搞糊涂 同时会妨碍代码在该作用域内的可移植性 void myMethod int int1 0 beginning of method block if condition int int2 0 beginning of if block 该规则的一个例外是 for 循环的索引变量 for int i 0 i maxLoops i 避免声明的局部变量覆盖上一级声明的变量 例如 不要在内部代码块中 声明相同的变量名 int count myMethod if condition int count 0 AVOID 社会保险管理信息系统核心平台三版本地化开发规范 第 11 页 类和接口的声明 Class and Interface Declarations 当编写类和接口时 应该遵守以下格式规则 在方法名与其参数列表之前的左括号 间不要有空格 左大括号 位于声明语句同行的末尾 右大括号 另起一行 与相应的声明语句对齐 除非是一个空语句 应紧跟在 之后 方法与方法之间以空行分隔 class Sample extends Object int ivar1 int ivar2 Sample int i int j ivar1 i ivar2 j int emptyMethod 2 3 语句语句 Java 中的简单语句 复合语句 返回语句 条件语句 try catch 语句等 应符合以下格式规范 简单语句 Simple Statements 每行至多包含一条语句 例如 社会保险管理信息系统核心平台三版本地化开发规范 第 12 页 argv Correct argc Correct argv argc AVOID 复合语句 Compound Statements 复合语句是包含在大括号中的语句序列 形如 语句 复合语句的书写规 则如下 被括其中的语句应该较之复合语句缩进一个层次 左大括号 应位于复合语句起始行的行尾 右大括号 应另起一行并与复合语句首行对齐 大括号可以被用于所有语句 包括单个语句 只要这些语句是诸如 if else 或 for 控制结构的一部分 这样便于添加语句而无需担心由于忘了 加括号而引入 bug 返回语句 return Statements 一个带返回值的 return 语句不使用小括号 除非它们以某种方式使返回值 更为显见 例如 return return myDisk size return size size defaultSize if if else if else if else 语句 if if else if else if else Statements if else 语句应该具有如下格式 if condition statements 社会保险管理信息系统核心平台三版本地化开发规范 第 13 页 if condition statements else statements if condition statements else if condition statements else statements 注意 if 语句总是用 和 括起来 避免使用如下容易引起错误的格式 if condition AVOID THIS OMITS THE BRACES statement for 语句 for Statements 一个 for 语句应该具有如下格式 for initialization condition update statements 一个空的 for 语句 所有工作都在初始化 条件判断 更新子句中完成 应该具 有如下格式 社会保险管理信息系统核心平台三版本地化开发规范 第 14 页 for initialization condition update 当在 for 语句的初始化或更新子句中使用逗号时 避免因使用三个以上变量 而导致复杂度提高 若需要 可以在 for 循环之前 为初始化子句 或 for 循环 末尾 为更新子句 使用单独的语句 while 语句 while Statements 一个 while 语句应该具有如下格式 while condition statements 一个空的 while 语句应该具有如下格式 while condition do while 语句 do while Statements 一个 do while 语句应该具有如下格式 do statements while condition switch 语句 switch Statements 一个 switch 语句应该具有如下格式 社会保险管理信息系统核心平台三版本地化开发规范 第 15 页 switch condition case ABC statements falls through case DEF statements break case XYZ statements break default statements break 每当一个 case 顺着往下执行时 因为没有 break 语句 通常应在 break 语句的 位置添加注释 上面的示例代码中就包含注释 falls through try catch 语句 try catch Statements 一个 try catch 语句应该具有如下格式 try statements catch ExceptionClass e statements 社会保险管理信息系统核心平台三版本地化开发规范 第 16 页 一个 try catch 语句后面也可能跟着一个 finally 语句 不论 try 代码块是否 顺利执行完 它都会被执行 try statements catch ExceptionClass e statements finally statements 2 4 缩进排版缩进排版 可使用集成开发环境中的自动智能缩进排版功能 手工排版时可参照如下 规则 行长度 Line Length 尽量避免一行的长度超过 80 个字符 因为很多终端和工具不能很好处理之 注意 用于文档中的例子应该使用更短的行长 长度一般不超过 70 个字符 换行 Wrapping Lines 当一个表达式无法容纳在一行内时 可以依据如下一般规则断开之 在一个逗号后面断开 在一个操作符前面断开 选择较高级别 higher level 的断开 而非较低级别 lower level 的断开 新的一行应该与上一行同一级别表达式的开头处对齐 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边 那就代之以 缩进 8 个空格 社会保险管理信息系统核心平台三版本地化开发规范 第 17 页 以下是断开方法调用的一些例子 someMethod longExpression1 longExpression2 longExpression3 longExpression4 longExpression5 var someMethod1 longExpression1 someMethod2 longExpression2 longExpression3 以下是两个断开算术表达式的例子 前者更好 因为断开处位于括号表达式的 外边 这是个较高级别的断开 longName1 longName2 longName3 longName4 longName5 4 longname6 应优选 longName1 longName2 longName3 longName4 longName5 4 longname6 应避免 以下是两个缩进方法声明的例子 前者是常规情形 后者若使用常规的缩进方 式将会使第二行和第三行移得很靠右 所以代之以缩进 8 个空格 CONVENTIONAL INDENTATION someMethod int anArg Object anotherArg String yetAnotherArg Object andStillAnother INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName int anArg Object anotherArg String yetAnotherArg 社会保险管理信息系统核心平台三版本地化开发规范 第 18 页 Object andStillAnother if 语句的换行通常使用 8 个空格的规则 因为常规缩进 4 个空格 会使语句体 看起来比较费劲 比如 DON T USE THIS INDENTATION if condition1 condition2 condition3 condition4 condition5 condition6 BAD WRAPS doSomethingAboutIt MAKE THIS LINE EASY TO MISS USE THIS INDENTATION INSTEAD if condition1 condition2 condition3 condition4 condition5 condition6 doSomethingAboutIt OR USE THIS if condition1 condition2 condition3 condition4 condition5 condition6 doSomethingAboutIt 这里有三种可行的方法用于处理三元运算表达式 alpha aLongBooleanExpression beta gamma 社会保险管理信息系统核心平台三版本地化开发规范 第 19 页 alpha aLongBooleanExpression beta gamma alpha aLongBooleanExpression beta gamma 2 5 空白空白 正确使用空格和空行 增强代码的可读性 下列情况应该总是使用两个空行下列情况应该总是使用两个空行 一个源文件的两个片段 section 之间 类声明和接口声明之间 下列情况应该总是使用一个空行 下列情况应该总是使用一个空行 两个方法之间 方法内的局部变量和方法的第一条语句之间 块注释或单行注释之前 一个方法内的两个逻辑段之间 用以提高可读性 下列情况应该使用空格 下列情况应该使用空格 一个紧跟着括号的关键字应该被空格分开 例如 while true 注意 空格不应该置于方法名与其左括号之间 这将有助于区分关键 字和方法调用 空白应该位于参数列表中逗号的后面 社会保险管理信息系统核心平台三版本地化开发规范 第 20 页 所有的二元运算符 除了 应该使用空格将之与操作数分开 一 元操作符和操作数之间不因该加空格 比如 负号 自增 和自减 例如 a c d a a b c d while d s n printSize size is foo n for 语句中的表达式应该被空格分开 例如 for expr1 expr2 expr3 强制转型后应该跟一个空格 例如 myMethod byte aNum Object x myMethod int cp 5 int i 3 1 2 6 注释规范注释规范 使用文档注释 document comments 注释 Java 的类 接口 构造器 方法以 及字段 field 文档注释文档注释 Documentation Documentation Comments Comments a 类注释 类说明 随机生成文件名 Copyright 2007 Beijing LBS Co Ltd author version 1 0 社会保险管理信息系统核心平台三版本地化开发规范 第 21 页 b 方法注释 比较两个日期 年月型 格式为YYYYMM 之间相差月份 param dealMonth 开始年月 param alterMonth 结束年月 return alterMonth dealMonth相差的月数 exception AppsException 业务异常信息 使用实现注释 implementation comments 注释代码或者实现细节 代码可以 有 4 种实现注释的风格 块 block 单行 single line 尾端 trailing 和行末 end of line 可以使用集成开发环境的自动注释功能帮助进行注释 注释格式的使用说 明如下 块注释块注释 Block Block Comments Comments 块注释通常用于提供对文件 方法 数据结构和算法的描述 块注释被置 于每个文件的开始处以及每个方法之前 它们也可以被用于其他地方 比如方 法内部 在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进 格式 块注释之首应该有一个空行 用于把块注释和代码分割开来 比如 Here is a block comment 单行注释单行注释 Single Line Single Line Comments Comments 社会保险管理信息系统核心平台三版本地化开发规范 第 22 页 短注释可以显示在一行内 并与其后的代码具有一样的缩进层级 如果一 个注释不能在一行内写完 就该采用块注释 参见 块注释 单行注释之前应 该有一个空行 以下是一个 Java 代码中单行注释的例子 if condition Handle the condition 尾端注释尾端注释 Trailing Comments 极短的注释可以与它们所要描述的代码位于同一行 但是应该有足够的空 白来分开代码和注释 若有多个短注释出现于大段代码中 它们应该具有相同 的缩进 以下是一个 Java 代码中尾端注释的例子 if a 2 return TRUE special case else return isPrime a works only for odd a 行末注释行末注释 End Of Line End Of Line Comments Comments 注释界定符 可以注释掉整行或者一行中的一部分 它一般不用于连 续多行的注释文本 然而 它可以用来注释掉连续多行的代码段 3编程技巧编程技巧 characters 转换到转换到 byte 数组数组 为了从 characters 得到 byte 数组 你可以这么做 社会保险管理信息系统核心平台三版本地化开发规范 第 23 页 Hello world getBytes 在 Java 中有很多类似的转换方法 在需要使用时应该多查找一下文档 不 要重复开发 JDK 中已经存在的系统方法 UtilityUtility 类类 Utility 类 仅仅提供方法的类 应该被申明为 final 的来防止被继承或 被初始化 数组初始化数组初始化 下面的代码是一种很好的初始化数组的方法 objectArguments new Object arguments 枚举类型枚举类型 JAVA 对枚举的支持不好 但可以用变通的方式来实现 但是下面的代码是 一种很有用的模板 class Colour public static final Colour BLACK new Colour 0 0 0 public static final Colour RED new Colour 0 xFF 0 0 public static final Colour GREEN new Colour 0 0 xFF 0 public static final Colour BLUE new Colour 0 0 0 xFF public static final Colour WHITE new Colour 0 xFF 0 xFF 0 xFF 这种技术实现了 RED GREEN BLUE 等可以象其他语言的枚举类型一样 使用的常量 他们可以用 操作符来比较 但是这样使用有一个缺陷 如果一个用户用这样的方法来创建颜色 BLACK new Colour 0 0 0 那么这就是另外一个对象 操作符就会产生错误 它的 equals 方法 仍然有效 由于这个原因 这个技术的缺陷最好注明在文档中 或者只在自己 的包中使用 调试调试 社会保险管理信息系统核心平台三版本地化开发规范 第 24 页 调试在软件开发中是一个很重要的部分 存在软件生命周期的各个部分中 调试能够用配置开 关是最基本的 很常用的一种调试方法就是用一个 debugFlag 类成员 在没有定义调试流 的时候就为 false 否则使用 true 来表示系统可以打印调试系统 4Java 性能优化性能优化 在写代码的时候 从头至尾都应该考虑性能问题 这不是说时间都应该浪 费在优化代码上 而是我们时刻应该提醒自己要注意代码的效率 比如 如果 没有时间来实现一个高效的算法 那么我们应该在文档中记录下来 以便在以 后有空的时候再来实现它 不是所有的人都同意在写代码的时候应该优化性能这个观点的 他们认为 性能优化的问题应该在项目的后期再去考虑 也就是在程序的轮廓已经实现了 以后 不必要的对象构造不必要的对象构造 不要在循环中构造对象 在必要的情况在循环的入口之前进行对象数据的 初始化 使用使用 StringBuffer 对象对象 在处理 String 的时候要尽量使用 StringBuffer 类 StringBuffer 类是构成 String 类的基础 String 类将 StringBuffer 类封装了起来 以花费更多时间 为代价 为开发人员提供了一个安全的接口 当我们在构造字符串的时候 我 们应该用 StringBuffer 来实现大部分的工作 当工作完成后将 StringBuffer 对 象再转换为需要的 String 对象 比如 如果有一个字符串必须不断地在其后添 加许多字符来完成构造 那么我们应该使用 StringBuffer 对象和它的 append 方法 如果我们用 String 对象代替 StringBuffer 对象的话 会花费许多不必要 的创建和释放对象的 CPU 时间 这一点尤其在构造较大的字符串时要告别注 意 使用使用 synchronized 关键字时应慎重关键字时应慎重 社会保险管理信息系统核心平台三版本地化开发规范 第 25 页 避免不必要的使用关键字 synchronized 应该在必要的时候再使用它 这 是一个避免死锁的好方法 5数据库访问性能注意事项数据库访问性能注意事项 在 java 业务代码中 获取数据库连接 访问数据库时消耗资源大 如频繁 访问数据库 将严重影响系统性能 因此在业务代码应尽量减少访问数据库的 次数 对于批量业务设计采用以下原则 a 尽量避免在循环中查询数据库 在批量业务代码中 尽量避免在循环中多次查询数据库 而应在循环外将所有 需要处理的数据查询处理后 在循环进行处理 减少访问数据库次数 从而提 高效率 b 采用异步提交模式 在批量业务代码 将查询运算的数据库连接与事务提交的数据库连接分别启动 查询数据并完成运算后 再启动事务及新建数据库连接进行提交数据 防止事 务超时和提高效率 c 采用批量提交模式 对于大批量保存和修改数据提交时 应该采用批量提交的 bath 而不是每 条进行提交 6程序兼容性注意事项程序兼容性注意事项 中文问题 在 webshpere 中 在 Action 中返回 forward 中如果出现传递中文信息时将 会造成乱码 因此应该避免在 Action 转向时传递中文的写法 例如 String param aab001 北京利博赛 forward new ActionForward CheckAction do method showDetail param true return forward 社会保险管理信息系统核心平台三版本地化开发规范 第 26 页 数据库移植性 在项目中使用 SQL 时 应考虑移植性 需要采用 SQL 标准写法 不要使 用特定数据库的语法 当标准 SQL 难以达到需要的效果时 可采用以下两种方 案 1 将一部分逻辑移至应用服务器处理 2 为主流的数据库服务器写多版本 的功能实现 Java 对象多态发布考虑 作为业务方法参数传递的对象应该实现可序化接口 这些对象包括实体对 象 DTO 等 当相应功能发布成 EJB 时不会导致错误 Java 中实现对象可序化的方法是类定义时声明实现 java