编码开发规范

1、海丰集运编码开发规范上海吉联新软件有限公司gl-07p-005 海丰集运综合业务管理信息系统编码规范说明书 中海集运滞期费管理信息系统中海集运文档编号：生效日期：密级：版本：r1.0编制： 审核：copyright notice copyright© 2003 - 2009 gillion technologies ltd.no part of this publication may be copied without the express writtenpermission of gillion technologies ltd.软件开发中心gillion restricted

2、page 17 of 17template version: 1.3last changed: 08 六月 2015 at 11:29修订历史daterevisiondescriptionauthor2014-01-04r1.0create林华导言51.1.编写目的51.2.内容边界51.3.术语及缩写51.4.文档结构51.5.参考文档51.声明5总体描述51.1.包51.2.类、接口61.3.方法61.4.字段61.5.代码示例72.命名7总体描述72.1.包与类命名82.1.1.包命名82.1.2.类命名82.1.3.entity对象命名82.1.4.service命名82.1.5.da

3、o命名92.1.6.exception命名92.2.属性命名92.2.1.成员变量和参数命名92.2.2.常量命名102.2.3.项目中控件/组件命名102.3.方法命名112.3.1.entity类中方法命名112.3.2.service类中方法命名112.3.3.项目中的方法命名123.注释12总体描述123.1.类、接口注释123.2.方法注释133.3.其它注释133.4.常用javadoc标记134.代码组织与风格14总体描述144.1.缩进144.2.长度144.3.行宽144.4.间隔154.5.括号155.性能与安全15总体描述155.1.通用性能优化155.1.1.strin

4、g与stringbugffer155.1.2.集合155.1.3.对象165.1.4.final165.1.5.abstract165.1.6.垃圾收集和资源释放165.1.7.慎用异常16 导言1.1. 编写目的本规范的目的是为了使海丰集运项目开发小组能以标准的、规范的方式进行编码。通过该规范的学习，以使开发人员养成良好的编码风格和习惯，并以此形成开发小组编码约定，提高程序的可靠性、可读性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。1.2. 内容边界结合项目实际开发情况和java基础语法知识,主要针对声明、命名、注释、代码组织与风格、性能和安全等方面进行规范和说明。1.3.

5、 术语及缩写全称含义1.4. 文档结构1.5. 参考文档资料名称位置1. 声明总体描述声明的基本原则是遵守java语言规范，并遵从项目习惯用法。 1.1. 包在导入包时当完全限制代码所有的类的名字，尽量少用通配符的方式，但导入一些通用包，或用到一个包下大部分类时，则可使用通配符方式,如：例如:import mons.beanutils.propertyutils;import java.util.*; 同意个包中的类的导入时当声明在一起，可由编辑器自动完成功能。eclipse采用ctrl+shift+o 导入包1.2. 类、接口类、接口定义语法规范：可见性('abstract'

6、|'final') class|interface class_name ('extends'|'implements')父类或接口名 例如： public class fuelsaveawardbygradeview extends commondataview 其中: abstract类含抽象方法的类，不能实例化，但允许继承他的子类实例化,只能单继承。 final类最终类，设计十分完美的类，不能有子类，不能在继承的类。1.3. 方法良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有

7、 (public)，就定义为保护 (protected)；没必要保护 (protected)，就定义为私有 (private)。 方法定义语法规范：可见性('abstract'|'final') 'synchronized'返回值类型 method_name(参数列表)('throws')异常列表 / 功能模块 例如： public list getalluserlist() throws daoexception 1.4. 字段字段定义语法规范：(public|private|protected) (final|volatile

8、)statictransient data_type field_name = expression ;例如：private string strusername=tom;1.5. 代码示例package com.sitc.rpt.rcp.viewpart;import java.math.bigdecimal;import java.util.arraylist;import java.util.list;import java.util.map;/* * author suzx * create_date 2009-01-01 * view_name 耗油/船速查询(按月份) */publ

9、ic class findconsumptionbymonthview extends baseviewpublic static final string id = "ful.findconsumptionbymonthview" /-常量protected static string name ="love"/ -实例变量 public string usercode="sh12345" /-公有字段protected float price =(float) 1.0; /-受保护字段private int count; /-私有

10、字段/公共方法public void getusername() /受保护方法-protected void convert() /私有方法-private void getusercode() 2. 命名总体描述规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。 2.1. 包与类命名2.1.1. 包命名海丰集运项目开发的应用包命名要求带有前缀com.sitc，采用“com.sitc.模块名.rcp.子功能包名”的形式，如“com.sitc.mkt.rcp.viewpart”。包名和子功能包名要求具有实际的意义，从单词或缩写上能够看出

11、包的意义。例如： 2.1.2. 类命名(1)类名首字母应该大写,之后连接的单词第一个字母大写，既所谓的驼峰法(2)类名要求不要过长，一般控制在30个字符以内(3)项目针对查询页面，编辑页面，弹出页面,报表等页面进一步做了一些规定:1.查询页面: find+实体名+view 或者 find+功能名+view例如: findmarketareaview 营销区查询 findonschedulestatisticsview 准班率查询2.编辑或者查询带编辑页面: edit+功能名+实体+view 例如: edit+marketareaview3.弹出框编辑页面: 功能+实体+dialog例如: se

12、lectcustomerdialog2.1.3. entity对象命名项目架构通过hibernate映射数据库，所以涉及实体的命名，该部分通过er图直接生成，所以相对规范,具体参考:<< 海丰集运数据库设计开发规范.doc>>例如：fuelsaveaward, fueltype, voyagepartition2.1.4. service命名service层主要负责处理系统的业务逻辑，一个主要的实体对应一个service，关于这个主要实体的操作都集中在service里面，主要涉及对象的粒度来定义一个接口和一个到多个实现。该部分通过工具直接生成，所以相对规范。示例： us

13、erservice, userserviceimpl1. service接口命名规范为：对象名+service2. service实现命名规范为：对象名+service+impl2.1.5. dao命名现在的框架不需要开发人员自己写dao代码，dao已经统一成commondao和commondaohibernateimpl,如果碰到特许情况需要自己开发dao的时候，按照以下规则：例如：userdaohibernateimpl, userdaojdoimpl, userdaocmpimpl1. dao接口命名规范为：对象名+dao2. dao实现命名规范为：对象名+dao+具体的o/r实现框架+

14、impl2.1.6. exception命名异常类名一般由表示异常类型的单词和exception组成，并且第一个字母大写。如:actionexception。逻辑名称+exception2.2. 属性命名java中成员变量又称成员属性，它是描述对象状态的数据，是类中很重要的组成成分， 成员变量是定义在类里面，并和方法处于同一层次。2.2.1. 成员变量和参数命名类的成员变量和在方法中所声明的局部变量即参数都是用户标识符，它们的命名规则相同，语法结构都是：变量修饰符 类型说明符 变量名 例如：private int nlen;1. 变量修饰符：修饰符声明了成员变量的访问权限，分别是：私有（pri

15、vate）、保护（protected）和公共（public）。除此之外，还有一种默认的访问权限。类型说明符：类型可以是java中的任意数据类型，包括基本类型、数组、类和接口。变量名：第一个字母小写，之后连接的单词第一个字母大写，如果是简写的单词全部大写。2. 静态成员变量：变量前加上static标识符 例如：protected static int stat=0;3. 静态变量的另一个用途是定义静态常量：public static double pi = 3.1415926;简单数据类型规范表：数据类型变量名前缀例子booleanbbcustomexist, bacustomexistchar

16、ccsymbol, casymbolsbyteyybyte, yabytesshortsshour, sahoursintnnlen, nloopcounter, nalengthlongllmemory, latimesfloatfflength, falengthdoubleddmile, damilesintegerintintquantitystringstrstrvesselnamebigdecimalbigbigpricedatedtdtstart注：byte与int类型的前缀较特殊，使用时应注意2.2.2. 常量命名常量在运行过程中是不可改变的，一般通过final static来

17、修饰, static用来修饰属性时称为静态属性，不属于某个具体的对象，属于类，但是所有的对象都能对其进行修改，单个final修饰的属性并不是常量，final表示的是不可改变性，但是属于某个具体的对象，两个加起来就是一个属于类并且不可改变的属性，即常量。包括：a.整型常量 123 ， b.实型常量 3.123 ， c.字符常量 a， d.逻辑常量 true,false，e.字符串常量“abcd”。常量命名：全部大写，相连的单词中间以”_”分开例如：public static final int default_page_size=1; private static final string st

18、r_world = "hello world!"2.2.3. 项目中控件/组件命名控件类型 gfa4j控件类前缀 例子check buttonchkbuttonchkchkactiveradion buttoncommonbuttonradradcitycommond button commonbuttonbtnbtnexitcommon dialog commondialogdlgdlgsltofficelabelcommonlabellbllblcodetext(text)commontexttxttxtnametext(date)datetexttxttxtetdte

19、xt(long)numbertexttxttxtlengthtext(bigdecimal）floatnumbertexttxttxtratecomboautoselectcombocbocbocountryselectcommoncodeselectcommoncodesccsccempnolistlistlstlstplacetreetreetretreconditiontablecommontabletbltblcustomertablecolumntablecolumncolcolplacecodetableitemudttableitemtblitmtoolbarcommontool

20、bartlbtlbsavetoolitemcommontoolitemtolitmmenuitemmenuitemmnugridgridtablegrtgrdcustomerdatepickdatepickercombodtpdatepick(time)datetimepickercombodtpgridlayoutgridlayoutgdlyfilllayoutfilllayoutfillyrowlayoutrowlayoutrowlyformlayoutformlayoutfrmlybordlayoutbordlayoutbrdlyflowlayoutflowlayoutflwlycomp

21、ositecompositecmpgroupgroupgrptabfoldertabfoldertabtabitemtabitemtabitmscrollcompositescrollcompositescmpgroupcommongroupgrpfieldfieldfldeditcompositeeditcompositeecpquerycompositequerycompositeqcmpmapautoselectcombomapautoselectcombomapcbosearchtoolbarsearchtoolbarstlbselecttextselecttextsltgriddat

22、agriddatagrd针对查询区域中的控件，建议加上srh，例如：lblsrhusername，txtsrhusername，目的是为了区分查询区的控件还是编辑区的控件。2.3. 方法命名 方法的命名采用完整的英文描述，大小写混合使用，第一个单词采用动词，并且小写开头，其他单词第一个字母大写。语法格式：访问性修饰符 非访问性修饰符 返回值 方法名() 2.3.1. entity类中方法命名entity是一个典型的值bean，所以方法一般情况下只有以下两种:例如:get+属性名set+属性名2.3.2. service类中方法命名因为xxxserviceimpl都是对xxxservice的实现

23、，所以xxxserviceimpl的方法命名和xxxservice的方法命名一致。u 添加：add+对象名。u 修改：update+对象名u 删除：remove+对象名u 典型查询：query+对象名u 特殊查询：find+对象名+by+条件名u 验证方法：validate+自定义标识2.3.3. 项目中的方法命名u 创建组件/部件：create +事件名u 初始化功能（如组件监听器、service等）：init +事件名u 执行操作（如执行删除按钮操作）：do+动宾+事件名,如dosavecustomer，dodeletecustomeru 有返回值的：get+事件名,如getcustome

24、rnameu 创建按钮权限createfunc+事件名,如createfunc2.4. er实体命名和表名 如果存在多表关联的情况，建议子表(第二层)=主表+item  ,从表(第三层)=主表+detl  例如：主表:repairrate  子表:repairrateitem  从表:repairratedetl如果表名太长采用:主表的缩写，缩写不超过4位，具体规则：多个单词组合的缩写取每个单词的首字母或头两个字母组成，同样不超过4个字符；例如：application_function = af (1:1)application_function = a

25、pfu (2:2)application_function_role = apfr (2:1:1)application_function_role_banana = afrb (1:1:1:1)3. 注释总体描述程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。3.1. 类、接口注释在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、创建日期

26、和修改记录有必要时还可以对继承的父类、实现的接口、实现的算法等进行注释。例如：/* * <p>类或接口描述 <p>* * 燃油航次分摊计算 * author guxg * version 1.0 $date*/3.2. 方法注释依据标准javadoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。参数注释时当注明其取值范围等返回值当注释出失败、错误、异常时的返回情况。异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常例如：/* 计算天数间隔* * 计算两个日期的天数间隔，永远返回正数或者零。 * param 时间一 * param 时间二

27、* return 时间间隔的天数 */ 3.3. 其它注释应对重要的变量加以注释，以说明其含义等。应对不易理解的分支条件表达式加注释。不易理解的循环，应说明出口条件。过长的方法实现，应将其语句按实现的功能分段加以概括性说明。对于异常处理当注明正常情况及异常情况或者条件，并说明当异常发生时程序当如何处理。针对这类情况的注释直接采用: /时间交叉判断3.4. 常用javadoc标记标签说明jdk 1.1 doclet标准doclet标签类型author 作者作者标识 包、 类、接口version 版本号版本号 包、 类、接口param 参数名 描述方法的入参名及描述信息，如入参有特别要求，可在此注

28、释。 构造函数、 方法return 描述对函数返回值的注释 方法deprecated 过期文本标识随着程序版本的提升，当前api已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个api。 包、类、接口、值域、构造函数、 方法throws异常类名 构造函数或方法所会抛出的异常。 构造函数、 方法exception 异常类名 同throws。 构造函数、 方法see 引用查看相关内容，如类、方法、变量等。 包、类、接口、值域、构造函数、 方法since 描述文本api在什么程序的什么版本后开发支持。 包、类、接口、值域、构造函数、 方法link包.类#成员 标签 链接到某个特定的成员对

29、应的文档中。 包、类、接口、值域、构造函数、 方法value 当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。 (jdk1.4)静态值域4. 代码组织与风格总体描述代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流,eclipse采用ctrl+shift+f格式化。4.1. 缩进子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。代码中以tab（4个字符）缩进，在编辑器中请将tab设置为以空格替代，否则在不同编辑器或设置下会导致tab长度不等而影响整个程序代码的格式。注：eclipse中用空格(space)代替制表符(

30、tab)的设置步骤窗口(windows)->首选项(preferences.)， 在左边选java->代码样式(code style)->格式化程序(formatter)， 右边点“显示(show)”按钮，选“缩进(indentation)”选项卡， 在“常规设置(general settings)”里的“跳格策略(tab policy)” 下拉列表选“仅空格(spaces only)”。4.2. 长度为便于阅读和理解，单个函数的有效代码长度当尽量控制在300行以内（不包括注释行），当一个功能模块过大时往往造成阅读困难，因此当使用子函数等将相应功能抽取出来，这也有利于提高代码

31、的重用度，尽量避免使用大类和长方法。4.3. 行宽页宽应该设置为100字符。一般不要超过这个宽度, 这会导致在某些机器中无法以一屏来完整显示, 但这一设置也可以灵活调整。在任何情况下, 超长的语句应该在一个逗号后或一个操作符前折行。一条语句折行后, 应该比原来的语句再缩进一个tab或4个空格，以便于阅读。4.4. 间隔类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行；操作符两端应当各空一个字符以增加可读性；相应独立的功能模块之间可使用注释行间隔，并标明相应内容。4.5. 括号 中的语句应该单独作为一行，左括号""当紧跟其语句后，右括号"&q

32、uot;永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。较长的方法以及类、接口等的右括号后应使用/end .等标识其结束。如:类的结束符：/eoc classname，方法结束符：/end methodname()，功能块结束：/end if.username is null?循环快结束：/end for.every user in userlist不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。5. 性能与安全总体描述 5.1. 通用性能优化5.1.1. string与stringbugffer不要使用如下string初始化方法：stri

33、ng str = new string(“abcdef”);这将产生两个对象，应当直接赋值：string str = “abcdef”;在处理可变 string 的时候要尽量使用 stringbuffer 类，stringbuffer 类是构成 string 类的基础。string 类将 stringbuffer 类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用 stringbuffer 来实现大部分的工作，当工作完成后将 stringbuffer 对象再转换为需要的 string 对象。比如：如果有一个字符串必须不断地在其后添加许多字

34、符来完成构造，那么我们应该使用 stringbuffer 对象和她的 append() 方法。如果我们用 string 对象代替 stringbuffer 对象的话，将会花费许多不必要的创建和释放对象的 cpu 时间。5.1.2. 集合避免使用vector和hashtable等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。在新的系统设计中不当出现这些实现，使用arraylist代替vector，使用hashmap代替hashtable。若却是需要使用同步集合类，当使用如下方式获得同步集合实例：map map = colle

35、ctions.synchronizedmap(new hashmap();由于数组、arraylist与vector之间的性能差异巨大，故在能使用数组时不要使用arraylist，尽量避免使用vector。5.1.3. 对象避免在循环中频繁构建和释放对象。不再使用的对象应及时销毁。5.1.4. final将参数或方法声明成final可提高程序响应效率，故此：注意绝对不要仅因为性能而将类、方法等声明成final，声明成final的类、方法一定要确信不再被继承或重载！不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成final所有方法参数声明成final私有(private)方法不需要声明成final若方法确定不会被继承，则声明成final5.1.5. abstractabstract修饰符用来