应用编码规范.doc

P17二期项目应用编码规范 集团信息技术部文档信息项目名称：项目经理：文档版本编号：项目阶段：文档版本日期：质量复审方法：起草人：起草日期：复审人：复审日期：版本记录版本编号版本日期修改者说明文件名目录1引言32Java开发规范42.1包名42.2一般类42.3抽象类42.4方法定义42.5静态方法42.6局部变量42.7注释5类注释规范5类属性注释规范5方法注释规范5代码间注释规范6注释内容要求62.8文件日志62.9操作日志72.10异常处理72.11单元测试72.12代码复用性82.13代码扩展性82.14性能优化82.15Java代码格式规范83页面端编码规范83.1JavaScript注释规范83.2JavaScript变量命名83.3JavaScript代码复用93.4页面规范91 引言为了使P17系统开发工作在规范中进行，根据本项目具体情况，约定开发规范，其中包括：后台Java、前台JavaScript以及页面展示的Freemarker，以便增加小组中代码可读性。2 Java开发规范2.1 包名所有包名应该全部小写业务部分所有包的起始部分com.cpic.p172.2 一般类1) 名字应该能够标识事物的特性。2) 名字可以有两个或三个单词组成，但通常不应多于三个。3) 使用名词或名词短语命名类。 4) 少用缩写。 5) 不要使用下划线字符 (_)。 例：public class CallSummarypublic class CallSummaryService2.3 抽象类和类命名规范相同，唯一区别是接口在名字前加上“Abstract”前缀public class AbstractServiceRequest2.4 方法定义1) 使用动词或动词短语命名方法。2) 第一个动词小写,后面单词首字母大写,用操作名称开头operationName 一些基本方法命名：set 设置 get 获得 is 是否 sum 汇总 execute 执行do 做querydelXXupdateadd Examples: private void setCompanyName(String strCompanyName);3) 方法中的参数命名采用Camel casing, 除了首字母小写外，其他所有单词第一个字母大写。2.5 静态方法静态方法每个单词首字母大写,其余小写。Examples: public static void startConnect(int intConnectID); 2.6 局部变量1) 局部变量名称 = 变量的前缀 + 代表变量含意的英文单词或单词缩写。变量前缀表示其类型，可参考如下：str-string;vct-Vector;flt-float;int-int;hat-HashTable;等等。 Examples: String strMAWBName; int intMAWBNum; 2) 即使对于可能仅出现在几个代码行中的生存期很短的变量，仍然使用有意义的名称。仅对于短循环索引使用单字母变量名，如 i 或 j。3) 不要使用原义数字或原义字符串，如 for i = 1 to 7。而是使用命名常数，如 for i = 1 to NUM_DAYS_IN_WEEK 以便于维护和理解。2.7 注释注释规范包括：类注释规范、类的属性、方法注释规范、代码间注释规范类注释规范类注释放在每个类定义的前面，格式如下： /* * * * author $Author: $ * 创建时间 格式 YYYY-MM-DD * */请在Eclipse里面设置模板，Windows菜单-Preference-Java-Code Style-Code Templates，把此注释加入类模板；或者使用时把上述程序段拷贝到每个class定义的前面，并把“” 替换成实际的class说明。类属性注释规范类的属性一般放在类的前面，格式如下： /* * 变量的注释 */Public int intParseFlag; 方法注释规范方法注释放在每个方法定义的前面，格式如下： 除了基本的get、set方法外，其它方法都需要加注释。方法注释的格式： /* * * * paramintSAC_Code客户id * paramstrBalanceType结算方式 * returnList * */请在Eclipse里面设置模板，Windows菜单-Preference-Java-Code Style-Code Templates，把此注释加入方法模板；或者使用时把上述程序段拷贝到method定义的前面，并用实际的内容替换“”。代码间注释规范代码间注释分为单行注释和多行注释：单行注释： /多行注释： /*多行注释1 多行注释2 多行注释3 */注释内容要求接口方法说明方法的功能，在什么情况调用等常量描述常量的作用，在什么情况下使用实现类public方法不仅描述方法的功能，还要描述具体实现步骤和实现方式protected方法需要描述方法的功能，并简要介绍内部实现逻辑private方法至少要描述方法的功能实例变量描述实例变量名字以及作用，如果是集合类（List、Map），那么必须描述清楚List中每行放的是什么内容，对与Map要求描述Key是什么，value是什么。类变量描述类变量的名字及作用方法内部要求每10行代码至少含一个注释，并且要求将逻辑步骤说明出来。2.8 文件日志日志级别：error warn info debug error用于记录影响系统正常运行的一切信息，包括：Exception、与其他系统通讯错误，例如：SQL执行异常、其他系统返回的错误信息； warn用于记录不影响系统正常运行，但需要注意需要及时解决，例如：某个信息； info通常生产环境的最低级别，用于记录这种重要的提示信息，例如：各种通讯信息，关键的提示信息，以及这种需要在生产环境下提示的信息； debug在生产环境中将不会出现此类信息（当然可能在某些特定情况下，通过特殊手段某一时间段可能打开用于生产环境调试），用于代替System.out，供开发阶段调试用。日志直接使用Log4j记录，在AbstractService已经为每个Service实现类提供了一个logger对象。具体要求如下：调试信息注意：禁止使用System.out或err方式打印调试信息，必须使用logger.debug替换，而且对于debug和info必须要先判断。日志级别对于重要的信息，例如：错误需要用warn或error打印信息。2.9 操作日志业务操作是否记录操作日志记录内容用户登录、退出坐席系统是用户代码、登录退出时间、是否成功业务对象的列表查询否具体业务对象的查看否具体业务对象的增加、修改、删除是业务对象类型、操作类型、操作对象主键批量任务处理（包括：服务任务和回访任务）是业务类型、操作类型，不记录批量操作的数据列表调用外部接口的查询否调用外部接口的交易是业务类型（接口类型）、操作类型、操作对象主键（记录接口编号）软电话状态变化是操作类型（示忙、示闲等）、扩展内容（示忙原因代码）2.10 异常处理异常处理禁止直接将异常打印出来，例如：e.printStackTrace()。非RuntimeException需要转成RuntimeException，此时采用UncheckedException。创建异常new RuntimeException（e）,并要求通过logger.error记录错误信息2.11 单元测试覆盖范围：所有Service的public方法，必须编写Junit的测试代码。单元测试代码的父类为：AbstractTestCase，依照此父类其加载顺序如下：1、自动加载coreContext.xml； 2、加载待测试的Spring配置，这一步有多种方法来加载，如下过程选择一个执行：情况1、默认情况加载与类名相同的XML配置文件，例如：com.test.TestUserService，那么将自动加载com/test/TestUserService.xml文件，如果此文件不存在，那么将自动装置所有的配置文件（classpath*:applicationContext*.xml）； 情况2、如果自己定义没有按照默认方法写了com/test/TestUserService.xml，而是希望加载另一个位置的配置文件，那么就需要覆盖getMappingConfig()方法，返回文件路径，例如：return com/unitest.xml; 3、在init(BeanFactory beanFactory)方法中得到Service实例；2.12 代码复用性要求：相同的代码不能出现在系统的任何位置两边或以上！即：任何问题在修改一个地方即解决了所有地方的问题。检查方法：所有代码不能重复，即采用Crtl+C复制的方式的代码都应该考虑抽取出方法，供多处调用。2.13 代码扩展性l 合理使用抽象类和接口；l 少用继承，多用组合；l 尽量减少对容器、框架的依赖，合理采用依赖注入、控制反转。2.14 性能优化l 合理采用缓存，尽量减少重复的查询；l 尽量不要在循环体内执行数据查询。2.15 Java代码格式规范1) 使用Eclipse的默认设置，所有的缩进为4个空格，。2) 在代码中的左括号和右括号要使用Eclipse的默认设置。(需讨论)例：if(x = 0)Response.Write(用户编号必须输入！);3) 为了防止在阅读代码时不得不滚动源代码编辑器，每行代码或注释在1024*800的显示频率下不得超过一显示屏（可以使用Eclipse的自动排版功能Ctrl+Shift+F来美化）4) 每一行上放置的语句避免超过一条。5) 在大多数运算符之前和之后使用空格，这样做时不会改变代码的意图 却可以使代码容易阅读。例：int j = i + k;而不应写为int j=i+k;将大的复杂代码节分为较小的、易于理解的模块。3 页面端编码规范3.1 JavaScript注释规范 *描述方面作用，实现逻辑，使用范围等。3.2 JavaScript变量命名1、所有类名、方法、变量、页面文件名等所有必须使用英文命名；2、所有英文必须符合developmentdocs03系统设计02概要设计02应用中英文对照.xls的要求；3、所有方法和变量命名都要求首字母小写；3.3 JavaScript代码复用所有代码不能重复，即采用Crtl+C复制的方式的代码都应该考虑抽取出方法，供多处调用。3.4 页面规范l 采用FreeMarker和Javascript共同实现： 页面展示部分（HTML）部分有FreeMarker实现，FreeMarker不仅可以方便的定义页面Marco，而且还可限制不能在页面中直接写Java代码； 而页面内容的提交和数据验证有Javascript结合Ajax技术实现； 页面展示文件为.xhtml，