JAVA编程规范v10.doc

《JAVA编程规范v10.doc》由会员分享，可在线阅读，更多相关《JAVA编程规范v10.doc（19页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、 JAVA编程规范编 号：版 本 号：受控状态：作 者：分 发 号： 第 3 页 共 33 页文档修改历史记录文档修改记录日 期版本号更改人更改内容文档审核记录日 期版本号审核人审核意见 密级:内部公开目 录1.Java 编程规范31.1 排版31.2 注释51.3 命名91.4 编码111.5 性能与可靠性152.基于Struts和EJB编程规约162.1 总体原则162.1.1 每个子系统纵向划分为五层），分别是：界面层、控制层、业务层、数据层162.1.2 界面层负责页面的展现,使用ExtJS162.1.3 控制层负责请求的转发，使用Struts Action162.1.5 业务层负责业

2、务的实现，使用EJB中的Session Bean162.1.6 数据层负责数据的存取，使用EJB中的Hibernate162.1.7 系统应严格遵循纵向分层的原则，在不同的层次中实现不同的功能162.2 Struts编程规约162.2.1 Struts配置文件定义162.2.2 struts2中减少action数量（通配符使用）162.2.3 事件定义172.2.4 参数信息获取172.2.5 命名规约182.3 EJB编程规约192.3.1 数据库连接192.3.3 命名规约191.Java 编程规范 1.1 排版规则1 分界符（如大括号和）应各独占一行，同时与引用它们的语句左对齐。在函数体

3、的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序或者static、,synchronized等语句块中都要采用如上的缩进方式。示例:if (ab) doStart();规则2 较长的语句、表达式或参数（80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。示例： if (logger.isDebugEnabled() logger.debug(Session destroyed,call-id + event.getSession().getCallId(); 规则3

4、 不允许把多个短语句写在一行中，即一行只写一条语句说明：阅读代码更加清晰 示例：如下例子不符合规范。Object o = new Object(); Object b = null;规则4 if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while,switch等语句的执行语句无论多少都要加括号,case 的执行语句中如果定义变量必须加括号。说明：阅读代码更加清晰，减少错误产生示例：if (ab)doStart();case x:int i = 9; 规则5 相对独立的程序块之间、变量说明之后必须加空行。 说明:阅

5、读代码更加清晰示例：if(a b)doStart();/此处是空行return;规则6 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如.），后不应加空格。说明：阅读代码更加清晰示例：if (a = b)objectA.doStart();a *= 2;规则7 类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。格式：类定义 类的公有属性定义 类的保护属性定义 类的私有属性定义 类的公有方法定义 类的保护方法定义 类的私有方法定义规则8 修饰词按照指定顺序书写：访问权限staticf

6、inal 。示例：public static final String str = “abc”;1.2 注释规则1 类和接口的注释放在class 或者 interface 关键字之前，import 关键字之后。注释主要是一句话功能简述与功能详细描述。类注释使用“/* */”注释方式说明：方便JavaDoc收集,没有import可放在package之后。注释可根据需要列出：作者、内容、功能、与其它类的关系等。功能详细描述部分说明该类或者接口的功能、作用、使用方法和注意事项，每次修改后增加作者和更新版本号和日期，since 表示从那个版本开始就有这个类或者接口，deprecated 表示不建议使用

7、该类或者接口。/* * 一句话功能简述 * 功能详细描述 * author 作者（必须）* see 相关类/方法（可选） * since 产品/模块版本 （必须） * deprecated （可选） */示例：package m;import java.util.*;/* * LogManager 类集中控制对日志读写的操作。 * 全部为静态变量和静态方法，对外提供统一接口。分配对应日志类型的读写器， * 读取或写入符合条件的日志纪录。 * author 张三，李四，王五* see LogIteraotor * see BasicLog * since CommonLog1.0 */publi

8、c class LogManager规则2 类属性(成员变量)、公有和保护方法注释：写在类属性、公有和保护方法上面，注释方式为“/* */”.示例：/* * 注释内容 */private String logType;/* * 注释内容 */public void write()规则3 公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、异常等。格式：/* * 一句话功能简述 * 功能详细描述 * param 参数1 参数1说明 * param 参数2 参数2说明 * return 返回类型说明 * exception/throws 异常类型 异常说明

9、* see 类、类#方法、类#成员* since 起始版本 * deprecated */说明：since 表示从那个版本开始就有这个方法，如果是最初版本就存在的方法无需说明；exception或throws 列出可能仍出的异常；deprecated 表示不建议使用该方法。示例： /* * 根据日志类型和时间读取日志。 * 分配对应日志类型的LogReader， 指定类型、查询时间段、条件和反复器缓冲数， * 读取日志记录。查询条件为null或0的表示没有限制，反复器缓冲数为0读不到日志。 * 查询时间为左包含原则，即 startTime, endTime) 。 * param logType

10、Name 日志类型名（在配置文件中定义的） * param startTime 查询日志的开始时间 * param endTime 查询日志的结束时间 * param logLevel 查询日志的级别 * param userName 查询该用户的日志 * param bufferNum 日志反复器缓冲记录数 * return 结果集，日志反复器 * since 1.2 */ public static LogIterator read(String logType, Date startTime,Date endTime, int logLevel, String userName, int

11、 bufferNum)规则4 对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出的异常，选择主要的在注释中说明。 对于非RuntimeException，即throws子句声明会抛出的异常，必须在方法的注释中标明。说明：异常注释用exception或throws表示，在JavaDoc中两者等价，但推荐用exception标注Runtime异常，throws标注非Runtime异常。异常的注释必须说明该异常的含义及什么条件下抛出该异常。规则5 对于switch语句下的case语句，必须在每个case分支结束前加上break语句。说明：break才能真正表示

12、该switch执行结束，不然可能会进入该case以后的分支。至于语法上合法的场景“一个case后进入下一个case处理”，应该在编码设计上就避免。规则6 修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。规则7 注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的注释不但无益反而有害。规则8 避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的说明。规则9 对重载父类的方法必须进行Override声明说明：可清楚说明此方法是重载父类的方法，保证重载父类的方法时不会因为单词写错而造成错误(写错方法名或者参数个数，类型都会编译无法

13、通过)示例：Overridepublic void doRequest(SipServletRequest req) throws ServletException,IOException规则10 避免在一行代码或表达式的中间插入注释。说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。规则11 在代码的功能、意图层次上进行注释，提供有用、额外的信息。说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。示例：如下注释意义不大。/ 如果 receiveFlag 为真if (receiveFlag)而如下的注释则

14、给出了额外有用的信息。 / 如果从连结收到消息 if (receiveFlag)规则12 对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。规则13 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。中文注释中需使用中文标点。方法和类描述的第一句话尽量使用简洁明了的话概括一下功能，然后加以句号。接下来的部分可以详细描述。说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文

15、。JavaDoc工具收集简介的时候使用选取第一句话。规则14 方法内的单行注释使用 /。说明：调试程序的时候可以方便的使用 /* 。*/ 注释掉一长段程序。规则15 一些复杂的代码需要说明。示例：这里主要是对闰年算法的说明。 /1. 如果能被4整除，是闰年； /2. 如果能被100整除，不是闰年； /3. 如果能被400整除，是闰年。1.3 命名规则1 类名和接口使用类意义完整的英文描述，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。示例：OrderInformation, CustomerList, LogManager, LogConfig, SmpTransaction规

16、则2 方法名使用类意义完整的英文描述：第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。示例：private void calculateRate();public void addNewOrder();规则3 方法中，存取属性的方法采用setter 和 getter方法，动作方法采用动词和动宾结构。格式：get + 非布尔属性名()is + 布尔属性名()set + 属性名()动词()动词 + 宾语()示例：public String getType();public boolean isFinished();public void setVisible(boolean

17、);public void show();public void addKeyListener(Listener);规则4 属性名使用意义完整的英文描述，第一个单词的字母使用小写，剩余单词首字母，常用的缩写字母要大写。规则5 大写其余字母小写的大小写混合法。属性名不能与方法名相同。示例： private customerName;private orderNumber;private smpSession;规则6 常量名使用全大写的英文描述，英文单词之间用下划线分隔开，并且使用 static final修饰。示例： public static final int MAX_VALUE = 100

18、0;public static final String DEFAULT_START_DATE = 2001-12-08;规则7 包名采用域后缀倒置的加上自定义的包名，采用小写字母，都应该以com. power开头(不包括一些特殊原因)。在部门内部应该规划好包名的范围，防止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名称。说明：除特殊原因包结构都必须以com. power开头，如果因为OEM合作等关系，可以不做要求。格式：com. power.产品名.模块名称示例：融合WEB包名 com. power.iin.web规则8 通过对函数或过程、变量、结构

19、等正确的命名以及合理地组织代码的结构，使代码成为自注释的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。规则9 常用组件类的命名以组件名加上组件类型名结尾。示例：Application 类型的，命名以App 结尾MainAppFrame 类型的，命名以Frame 结尾TopoFramePanel 类型的，建议命名以Panel 结尾CreateCircuitPanelBean 类型的，建议命名以Bean 结尾DataAccessBeanEJB 类型的，建议命名以EJB 结尾DBProxyEJBApplet 类型的，建议命名以Applet 结尾PictureShowAp

20、plet规则10 如果函数名超过15 个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。示例：getCustomerInformation() 改为 getCustomerInfo()规则11 准确地确定成员函数的存取控制符号:只供该类内部调用的函数使用 private 属性，可供继承类使用的函数使用protected属性，可供同包类调用的函数使用默认属性(不加属性控制符号)，对外公开的函数使用public属性。示例： protected void getUserName()。private void calculateRate()。规则12 含有集合意义的属性命名，

21、尽量包含其复数的意义。示例：customers, orderItems1.4 编码规则1 数据库操作、IO操作等需要使用结束close()的对象必须在try -catch-finally 的finally中close()，如果有多个IO对象需要close()，需要分别对每个对象的close()方法进行try-catch,防止一个IO对象关闭失败其他IO对象都未关闭。示例：try / . .catch(IOException ioe) /. .finally try out.close(); catch (IOException ioe) /. .try in.close(); catch (I

22、OException ioe) /. . 规则2 系统非正常运行产生的异常捕获后，如果不对该异常进行处理，则应该记录日志。 说明：此规则指通常的系统非正常运行产生的异常，不包括一些基于异常的设计。若有特殊原因必须用注释加以说明。示例：try /. .catch (IOException ioe) logger.error(ioe);规则3 自己抛出的异常必须要填写详细的描述信息。说明：便于问题定位。示例：throw new IOException(Writing data error! Data: + data.toString();规则4 注意运算符的优先级，并用括号明确表达式的操作顺序，避

23、免使用默认优先级。说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。示例：下列语句中的表达式word = (high 8) | low (1)if (a | b) & (a & c) (2)if (a | b) (c & d) (3)如果书写为high 8 | lowa | b & a & ca | b c & d（1）（2）虽然不会出错，但语句不易理解；（3）造成了判断条件出错。规则5 避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不应直接使用数字，必须用有意义的静态变量或者枚举来代替。使用异常来表示方法执行错误，而不是使用C+

24、的错误返回码方式。示例：如下的程序可读性差。if (state = 0) state = 1; . / program code应改为如下形式：private final static int TRUNK_IDLE = 0;private final static int TRUNK_BUSY = 1;private final static int TRUNK_UNKNOWN = -1;if (state = TRUNK_IDLE) state = TRUNK_BUSY; . / program code注意：Java 5.0 下建议使用枚举来表示。异常：public void functi

25、on(). throw new RuntimeException(“。”);规则6 数组声明的时候使用 int index ，而不要使用 int index 。说明：使用int index 格式使程序的可读性较差，int index 表示声明了一个int数组(int )叫做index示例：如下程序可读性差：public int getIndex() .如下程序可读性好：public int getIndex() .规则7 不要使用 System.out 与 System.err 进行控制台打印，应该使用工具类(如：日志工具)进行统一记录或者打印。说明：代码发布的时候可以统一关闭控制台打印，代码

26、调试的时候又可以打开控制台打印，方便调试。规则8 集合必须指定模板类型说明：方便程序阅读，除去强制转换代码示例：Map map = new HashMap();规则9 一个文件不要定义两个类(并非指内部类)。说明：方便程序的阅读与代码的维护规则10 判断语句不要使用”* = true”来判断为真说明：方便阅读，减少没有必要的计算以下错误：if (ok = true)以下正确：if (ok)规则11 不要写没有必要的向上强制转型。说明：没必要写的向上强制转型会浪费性能，增加代码阅读难度示例：以下错误：FileInputStream fis = new FileInputStream(f);Inp

27、utStream is = (InputStream)fis;规则12 集合中的数据如果不使用了应该及时释放，尤其是可重复使用的集合。说明：由于集合保存了对象的引用，虚拟机的垃圾收集器就不会回收。规则13 源程序中关系较为紧密的代码应尽可能相邻。说明：便于程序阅读和查找。示例：矩形的长与宽关系较密切，放在一起。 rect.length = 10;rect.width = 5;规则14 不要使用难懂的技巧性很高的语句，除非很有必要时。说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于设计与算法。规则15 明确方法功能，精确（而不是近似）地实现方法设计。一个函数仅完成一件功能，即使简单功

28、能也编写方法实现。 说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。规则16 对接口方法参数的合法性检查应必须由方法的调用者负责。说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。规则17 尽量使用Java 5.0新循环写法。说明：代码更加简洁示例：ArrayList list = new Arra

29、yList();list.add.for(String str:list)System.out.println(str);规则18 interface 中定义的常量不要写public、static、final的修饰词，方法不要写public修饰词。说明：更加简洁示例：public interface InterfaceT String TT = abcl; void doStart();规则19 新起一个线程，都要使用Thread.setName(“”)设置线程名。说明：性能测试时可对线程状态进行监控，异常时也可以知道异常发生在哪个线程中1.5 性能与可靠性规则1 数组复制使用System.a

30、rraycopy(*) 。说明：更好的性能规则2 不要使用循环将集合转为数组，可以使用集合的toArray()方法。说明：更好的性能，代码更加简洁示例：ArrayList list = new ArrayList(); list.add. String array = new Stringlist.size(); list.toArray(array);规则3 大量字符串的相加等于处理应该使用StringBuffer。说明：大量的String相加等于处理性能消耗较多。“大量”一般指5次“+=”以上或者在循环中进行字符串+=操作。示例：不推荐：String str = “”;str += ”a”

31、;str += ”b”;推荐：StringBuffer sb = new StringBuffer();sb.append(“aa”);sb.append(“bb”);sb.append(“cc”);2.基于Struts和EJB编程规约2.1 总体原则2.1.1 每个子系统纵向划分为四层），分别是：界面层、控制层、业务层、数据层2.1.2 界面层负责页面的展现,使用ExtJS2.1.3 控制层负责请求的转发，使用Struts Action2.1.5 业务层负责业务的实现，使用EJB中的Session Bean2.1.6 数据层负责数据的存取，使用EJB中的Hibernate2.1.7 系统应严

32、格遵循纵向分层的原则，在不同的层次中实现不同的功能2.2 Struts编程规约2.2.1 Struts配置文件定义对于系统中的某个模块，需要在开发前定义该模块的配置，该struts的配置文件命名为：xxx_struts.xml xxx为模块的小写英文名或缩写，如：resource _struts.xml注意：中间为“_”，而不是“-”连接符，将所有的struts配置文件全部放到src下的config.struts目录中，然后在src下的struts.xml文件中引入配置文件。例如：2.2.2 struts2中减少action数量（通配符使用）如struts中配有如下几个action，Manag

33、erUserAction中有与之对应的方法开发时使用统一的命名规范，给类命名之前，要先确定项目里有没有同名的类，要保证类名唯一，则同一个包下的所有action可使用类似如下的一条替换即可如上所示，所有文件都采用统一的命名规范，第一个*为分类名称，第二个*为操作名，1和2分别代表第一个和第二个*的替换值，所有action实现类都命名为分类名称+Action。如分类名称为User，操作名为add，则访问的action名为User_add.action，action实现类名为UserAction 2.2.3 事件定义事件对应的类主要有Action，还有js中提交的“.action”定义，以及页面动作

34、的提交，以login登录为例：页面动作定义:Action则定义为LoginAction统一继承AbstractAction父类。成员变量都为私有，查询统一为findXXX，增加和修改统一为saveOrUpdateXXX，删除统一为deleteXXX，构造函数里实例化sessionbean统一为factory.getFacadeRemote(XXX);一个url xx.action对应一个方法.2.2.4 参数信息获取规则1 公共参数信息公共参数信息通过Plugin方式在Web服务启动时将变量放入application中，使得在任何需要该变量的jsp中都可以调用；方式如下：public void

35、 setServletContext(ActionServlet actionServlet) try ServletContext sc = actionServlet.getServletContext();/SysInitPwdsc.setAttribute(Constants.SYS_INIT_PWD,SelectLists.getSysConfig(PWDINIT);在action等程序中的调用方式：getServlet().getServletContext().getAttribute(“”);规则2 页面展示数据对于页面上需要展示的数据尽量存放在request这个范围里，可以减

36、轻服务器端内存负载，存放在SESSION中的数据需经过项目评审，方式如下：/调用员工处理类StaffDeal sd=new StaffDeal();/根据员工状态查询员工ArrayList al=sd.qryStaff(strState);/放入requestrequest.setAttribute(staffInfo,al);规则3 尽量（新增）避免使用Java语句JSP页面中应只使用JavaScript，CSS和Struts Tag，避免直接使用Java语句。其中JavaScript和CSS都必须通过外部文件的形式使用规则4 避免反复全部刷新页面应使用iframe局部刷新技术和AJAX技术

37、,只刷新需要的部分数据，避免反复全部刷新页面，提高页面响应速度规则5 合并多个类似的页面多个类似的页面，必须合并为一个页面，便于扩展和维护规则6 对大量数据的显示要使用分页对大量数据的显示，要使用分页技术，提高页面响应速度2.2.5 命名规约规则1 Action类及Action Name的命名规范Action类的后缀统一加上Action，Action的Name与类的名称保持一致，但不要Action的后缀。这样是为了通过Action的调用url， 很方便的找到Action类。1 3 /demo/search.jsp 4 如上，看到/searchKnowledge.action，就可以很清楚的知道

38、类是SearchKnowledgeAction了。很多人不注重这一点，开发调试中，每次都要笨拙的看struts.xml文件。查询方法名称统一为findXXX,增加修改方法名称统一为saveOrUpdateXXX,删除方法统一为deleteXXX。规则2 配置文件的目录结构规则3 不断的提炼公用的Action，并放在一个package中：如上传、下载、异常处理、excel数据录入、过滤器（filter）、截取器（inteceptor）等等规则4 将一个模块中的Action放置在一起规则5 明确Action类不要超长，如不要超过500行代码，除非必要。说明：很多人为了偷懒，喜欢在一个Action中

39、，不断的添加方法，而不管这些方法与Action的语义是否符合，到底是多个Action，还是多个方法，在开发过程中，还是要注重这些方法是否与创建Action类的目的、语义保持一致。规则6 页面地址定义（首字母需小写）如果有两个单词以上，第二个单词首字母大写，依此类推，形式为“动作名”如：login. action或loginSys. action。jsp文件命名也按此规范2.3 EJB编程规约2.3.1 数据库连接规则1 数据源数据源应直接使用应用服务器datasource，配置JNDI名称进行使用规则2 数据库连接池数据库连接池应使用应用服务器提供的连接池，以得到最高的效率2.3.3 命名规约规则1 实现类及接口的命名规范实现类和接口都通过反转生成，接口里的每个方法都要写注释。如下图/*查找战略目标树列表信息param nodereturn*/public List findTargetTreeList(String node);规则2 不断的提炼公用的方法，并放在一个package中：如上传、下载、异常处理、excel数据录入，报表的导出等等规则3 将一个模块中的接口和实现类还有实体bean放置在一起规则4 明确实现类不要超长，如不要超过500行代码，除非必要。规则5 涉及到多表之间业务比较复杂的新建个接口和实现类。