Chinapay技术部Java编码规范.docx

Chinapay技术部Java编码规范（Version: 0.14）版本变迁记录：版本号修改人时间修改内容备注V0.10钱斌2010-06-28创建文档初稿V0.11钱斌2010-07-071. 增加bug和性能优化的注释说明2. 禁忌中增加对第三方api引入的说明根据周翔的建议增加V0.12钱斌2010-07-071. 增加对大括号换行的说明。2. 增加对标识符的cp标识的说明根据周雪松建议增加V0.13钱斌2010-07-081. 增加对jar包的说明。2. 增加配置文件的规范说明V0.14钱斌2010-07-081. 修改jar包的发布说明目录Chinapay技术部Java编码规范11.概述42.源程序编程规范42.1.命名规范42.1.1.类和接口的命名42.1.2.方法的命名52.1.3.变量的命名52.1.3.1.静态常量的命名52.1.3.2.枚举的命名62.1.3.3.普通变量的命名62.1.4.包的命名62.1.5.Jsp文件及变量的命名72.2.注释及空白规范72.2.1.注释规范72.2.2.Java doc规范72.2.3.空白的规范72.2.3.1.空行的规范72.2.3.2.空格的规范82.2.3.3.缩进的规范82.2.3.4.折行、换行规范83.日志规范94.异常处理的规范95单元测试规范96其他禁忌101. 概述本标准定义了chinapay技术部java语言开发的编程格式规范，主要包括命名规范、代码注释、日志、以及常用语句的书写要求和约束等。统一规范的格式有利于代码标准化、提高代码的可读性，从而方便后面维护人员对系统业务流程的理解，便于对系统的进行改造和功能扩展。适用对象包括java源程序和jsp代码。2. 源程序编程规范2.1. 命名规范所有的标识符的命名力求做到统一、达意和简洁。如下为标识符的总原则，本章节的所有不同类型的标识符都必须首先符合本原则：1) 统一：对于同一个概念，在程序中用同一种表示方法。比如对于金额，如果定义了amt，则不要再变成其他名称。2) 达意：标识符能准确的表达出它所代表的意义，比如： BaseOperDBDAO，GenBankFileProcess等。切忌用tmp，server1,server2等之类的命名。3) 简洁：在统一和达意的前提下，用尽量少的标识符。如果不能达意，宁愿不要简洁。4) 骆驼法则：Java中，除了包名，静态常量等特殊情况，大部分情况下标识符使用骆驼法则，即单词之间不使用特殊符号分割，而是通过首字母大写来分割。比如: SupplierName, addNewContract，而不是 supplier_name, add_new_contract5) 命名尽量使用通俗易懂的英文单词，如果不会可以向同事求助，不可使用拼音。6) 对于chinapay的业务流程相关的标识符，建议加上cp前缀。2.1.1. 类和接口的命名1) 类名首字母必须大写。例如： ThisIsAClassName.java。2) 一定集合的类定义了统一的后缀。如下是常见的类的后缀，如果属于如下集合，请务必按清单中的后缀给类命名。请注意后缀的大小写。a) Action：Struts的action类，例：Commit3015Action。l 不同的项目对action要求不一样，如果需要权限控制，则通常在类中需要有权限id，用来过滤url的请求权限。l 每个action必须加action后缀，但是struts-config.xml中的配置需要去除action。例：类名为Commit3015Action.java，配置中则为：Commit3015.do。b) Form：Struts的form类，例：Perform3013Form。l 跟action一一对应。也可多个action公用一个form。命名通常跟action配套，如action名为Commit3015Action，则form应命名为Commit3015Form。c) Bean：数据库对象，例：CardBinBean。l 类名通常跟数据库表一一对应，如表名为card_bin，则对应的bean名称为CardBinBean。l Bean必须直接或间接继承自toolkit.bean.RecordBeanImpl.RecordBeanImpl。目前已经实现了一个根据表结构生成bean的工具，可用此来生成。d) DAO：数据库操作对象，例：CardBinDAO。l 所有的数据库操作必须在DAO中进行。后缀统一为DAO，不可写成Dao。l 如果DAO为小表，建议用不要每次都访问数据库，可以实现com.chinapay.memory.MemoryFlushInf接口。需要在控制台可以手动更新内存。e) Servlet：servlet类，例：LoginServiceServlet。l Servlet类必须加此后缀。l 理论上，如果采用struts框架或者其他mvc框架，尽量少用servlet。f) BO：复杂业务逻辑类。例：UserBO。l 对于复杂的业务逻辑，需要独立出BO来处理。BO不可写成Bol 在时间允许的情况下，BO必须编写单元测试，并且案例必须覆盖所有分支。g) Process：与BO类似，处理复杂业务逻辑。例如：GenBankFileProcessl Process通常指交易的业务处理流程。BO倾向于控台的复杂业务流程。由具体项目经理指定采用那个后缀。l 在时间允许的情况下，Process必须编写单元测试，并且案例必须覆盖所有分支。h) Filter：过滤器。例如：AuthFilteri) Task：系统任务。通常为定时任务。例如：UsrTransLogTask。j) Util：util类。例如：EncryptorUtil。2.1.2. 方法的命名1) 首字母小写，如 getDebitList() 不要 GetDebitList ()2) 动词在前，如 getDebitList() 不要debitListGet()3) 尽量清晰的表达该方法的作用2.1.3. 变量的命名2.1.3.1. 静态常量的命名全大写用下划线分割，用final关键字。如：public static final String FORWARD_GLOBAL_ERROR=”error”;2.1.3.2. 枚举的命名全大写，用下划线分割，如public enum Events ORDER_PAID,ORDER_CREATED2.1.3.3. 普通变量的命名首字母小写。尽量不要和域变量或者全局变量的名称冲突（理论上，我们不推荐使用全局变量，少使用域变量，尽量把变量的作用域控制到最小）。实例： String orderId;2.1.4. 包的命名使用小写字母。此处不再用骆驼法则，因为包名的所有字符都是小写，不要用分隔符。如：com.chinapay.newgms，不要com.chinapay.NewGms也不要com.chinapay.new_gmsl 包名的前两位必须是com.chinapay，后面是具体的项目名称或者jar包的名称。l Chinapay目前已经存在的公用jar包及定位：Jar包名称用途修改权限修改规则biz.jar公用数据库操作的jar。接近废弃。不修改。可继承使用newchinapay.jar主要是一些公用类和数据库封装类。通常公用的一些处理可先在此jar包中寻找，建议统一调用，以利于优化。需要主管以上人员批准新增为主，尽量避免修改（除非有bug）。SecureKit.jar连接S_server的接口包理论上不作修改dbaccess_for_jdk1.4.jar数据库访问的封装类理论上不作修改utils_for_jdk1.4.jar公用的处理类。基本上很少用，跟dbaccess配套使用。理论上不作修改netpayclient.jar商户签名验签api专人负责修改新增为主，尽量避免修改（除非有bug）。gms.jar废弃不修改不修改chinapay.jar废弃不修改不修改netpay.jar废弃不修改不修改l 除如上公用jar包外，本项目的Java程序建议都以class方式发布，不推荐用jar包方式发布。2.1.5. Jsp文件及变量的命名Jsp文件名称遵循java文件的规范。Jsp中的变量也遵循java变量的规范。但是在jsp中，不可以有业务逻辑。2.2. 注释及空白规范2.2.1. 注释规范一般来说，注释的使用应按照以下原则：l 注释应该能够帮助读者理解代码的功能和作用，应该有助于读者理解程序的流程。l 注释宜详不宜简。在没有信心表达清楚的情况下，宁可多写，不可少写。l 命名达意，结构清晰， 类和方法等责任明确，往往不需要，或者只需要很少注释，就可以让人读懂；相反，代码混乱，再多的注释都不能弥补。所以，注释不能替代代码，并不是说有了注释，就可以把代码写的杂乱无章。l 不能正确表达代码意义的注释，只会损害代码的可读性。所以，务必保持注释跟代码的一致性。l 注释不是用来管理代码版本的，如果有代码不要了，直接删除，cvs会有记录的，不要注释掉，否则以后没人知道那段注释掉的代码该不该删除。l 临时的注释用“temporary note”进行标注，以利于将来程序发布时将其删去。l 对于特殊的代码写法，或者因怪异的需求而添加的代码，必须写上注释说明该代码的作用和历史原因。l 在bug修正和程序优化的代码点,需要注释何时,为何更改。2.2.2. Java doc规范Java doc的关键字和写法请参加sun的官方文档，此处不详细展开。对于java doc，本规范定义了如下原则：l 每一个java类，接口，方法，属性都必须写上java doc与之对应，说明类、接口、方法、属性的作用，对于类和接口，还需要写明作者、公司（ChinaPay）、版本信息、修改记录。一旦代码有更新，java doc必须随之更新。l 对于废弃的类和方法，需要及时在java doc中用deprecated关键字声明。2.2.3. 空白的规范2.2.3.1. 空行的规范空行的使用有益于将代码按照逻辑分段，提高代码的可读性。在下列情况下建议使用一个空行：l 在类的声明之间；l 在方法的声明之间；l 在类中声明最后一个属性之后，声明第一个方法之前。l 在一段类似的语句块之后l 在判断语句开始之前l 在循环开始之前l 超过十行的代码如果还不用空行分割，就会增加阅读困难 l2.2.3.2. 空格的规范1) 下列情况建议使用单个空格（不是Tab）:a) 方法的参数之间，逗号右端需要有空格。b) 赋值语句“=”两端需要有空格隔开。2) 下列情况不建议使用空格a) 左括号和后一个字符之间不应该出现空格b) 大括号后面不应该出现空格c) 语句结束后的分号后不应该出现空格d) 右括号和前一个字符之间也不应该出现空格2.2.3.3. 缩进的规范缩进是为了方便代码阅读，通常使用tab。一个tab为4个空格长度。1) 判断，循环，方法首行需要一个tab缩进，余下的代码跟首行一致2) case语句首行需要一个tab缩进，余下的代码跟首行一致2.2.3.4. 折行、换行规范l 代码中的行应该为120列，源代码一般不会超过这个宽度, 如超过了120列应该截成较短的行，建议超长的语句应该在一个逗号或者一个操作符后折行。一条语句换行后, 应该比原来的语句有所缩进，缩进的具体格数要依据该语句的类型。l 大括号的折行。对于“”，不独立一行，而是的右边有换行符。而“”则需要独立一行。规范的写法如下：for(.) 如下是不推荐的写法：for(.) 3. 日志规范l 如项目无特殊说明，记录日志统一采用com.chinapay.util.log.TraceLog.java来记录。代码中不允许出现System.out/System.err。l 日志的等级通常分为debug，info，warn，error，fatal五个级别。在一般使用中，只会用到debug，error，和fatal 3个级别。如项目中没有其他说明，则只需用此3个级别。以下是对级别的说明：n debug：用来跟踪代码执行情况。此日志级别最为常见，系统维护人员可以根据该记录定位问题，分析问题。n error：当程序出现业务错误的时候需要记录。比如当交易处理过程中，判断提交的数据不合法时，此时应该记录error日志。n fatal：当程序发生系统异常的时候需要记录fatal日志。比如无法获取数据库连接，或者io异常等情况。l 记录的日志必须记录调用此日志的类名。正确的做法：TraceLog.debug(this, 日志测试”);/非静态调用TraceLog.debug(“com.chinapay.ora.util.SystemParams.java”, 日志测试”);/静态调用错误的做法：TraceLog.debug(日志测试”);/这种调用不允许出现。l 抓获的异常堆栈的日志需要用tracelog记录下来。不能用e.记录方式：trycatch (Exception e) TraceLog.logStackTrace(this, (Throwable)e);finally4. 异常处理的规范略5 单元测试规范l 单元测试的代码也需要提交（并不强制编写，但是复杂的类需要实现），不要跟代码混在一起，另建一个java源文件目录。比如通常src目录为代码目录，测试的目录可以跟src同父目录的test目录。通常由JUnit实现，对于一个项目，需要有个总的入口可以调度这些单元测试。l 单元测试需要符合JUnit规范，即初始化函数初始化测试所需的数据，销毁函数负责清扫测试数据，回复原始状态。l 对于复杂业务流程的类，需要有详尽的测试类与之对应，要能覆盖绝大部分的案例。6 其他禁忌l 不允许写内嵌类，每个java文件只能有一个java类l 在