Java开发规范.doc

Java开发规范1 概述为了使代码清晰易懂，使别的程序员能够容易理解代码所进行的实际工作，因此建立代码编写规范，形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性、可继承性和一致性，不但可以保证程序代码的质量，而且可以继承软件开发成果，充分利用资源，使开发人员之间的工作成果可以共享。说明：该规范中蓝色斜体部分需要各项目小组制定开发规范的时候具体定制。具体定制请删除蓝色斜体部分。2 开发环境规范项目统一使用UTF-8编码。任何开发规范文档中必须统一规定JDK、应用服务器、数据库、开发工具，和它们的具体版本号(包括小版本号)。名称版本号JDKsun jdk1应用服务器tomcat5.5.25数据库oracle11g开发工具red hat devloper studiobeta23 后台编码规范3.1 变量命名规范l 第一个字母小写，之后每个单词间的首字母大写。例如：userName，password等l 静态常量字段（static final） 全部采用大写字母，单词之间用下划线分隔。例如：MIN_BALANCE, DEFAULT_DATEl 避免使用下划线（除静态常量等）l 避免使用类似的名字，或者仅仅是大小写不同的名字l 如果变量是集合，则变量名应用复数。例如：int students;3.2 函数命名规范l 函数名称第一个字母小写，之后每个单词间的首字母大写。例如：public Userinfo getUserByName(String userName)和业务相关的函数命名方式，请参见“业务逻辑层编码规范”“DAO层编码规范”。3.3 类命名规范l 类首字母必须大写，每个单词的首字母也必须大写。l ManagedBean、Service、DAO命名规则名称命名规则Manage BeanXXXManagedBeanServiceXXXServiceDAOXXXDAO注：XXX是需根据实际业务替换的名称l 其他类可以根据需要自行命名3.4 包定义规范3.4.1 包命名规范l 包名必须小写。l 命名方式：com.globalzt.项目名称.模块名(.次级模块.).层名3.4.2 包规划名称包路径请求处理层com.globalzt.项目名称.模块名(.次级模块.).view业务逻辑层com.globalzt.项目名称.模块名(.次级模块.).serviceDAO层com.globalzt.项目名称.模块名(.次级模块.).daomodel路径com.globalzt.项目名称.common.model和业务有关的公共的部分com.globalzt.项目名称.common和业务无关的公共的部分mon和业务有关的工具包com.globalzt.项目名称.util和业务无关的工具包com.globalzt.framework.util3.5 常量定义规范l 所有常量遵循“变量编码规范”中的常量部分的定义。l 如果该常量只与自己类相关，则定义到自己类里面。例如：public final class java.util.Locale implements java.lang.Cloneable, java.io.Serializable public static final java.util.Locale ENGLISH; public static final java.util.Locale FRENCH; public static final java.util.Locale GERMAN; 注：此例使用了java.util.Locale类的常量定义l 其他常量定义到com.globalzt.项目名称.common.Constants里，按照不同分类，添加进自己的内部类里面。例如：public class Constants public static class Common public static final String USER_INFORMATION=USER_INFORMATION; 3.6 注释规范3.6.1 类注释格式如下：/* * 类的说明 * Copyright (c) 2008 * 公司名称 * author 作者 时间 * version 1.0 */示例：/* * 用户登录类 * author 唐杰 2008-07-24 * version 1.0 */3.6.2 函数注释l 注释格式/* * 函数功能解释 * param 参数名称1 参数解释 * param 参数名称2 参数解释 * return 返回值解释 * 创建者 创建时间 * 修改者 修改时间 修改内容 */示例：/* * 根据用户名查询一个用户 * param userName 用户名称 * return 用户对象 * 唐杰 2008-07-23 * 何刚 修改 2008-07-24 增加MD5加密算法 */l 除了属性的get、set函数外，其他函数必须加上注释，注释里必须标明作者、修改者以及时间3.6.3 变量注释变量的注释使用/，并写在变量申明的上方或者后方。例如：/用户名private String userName;3.6.4 程序代码片断注释程序代码段的注释可以使用/* */和/两种形式，请自行选择。例如：/ 获取user服务UserService us = (UserService) this.getService(userService);3.6.5 修改程序代码的注释修改别人的代码或者在别人函数里新增代码，需要在自己新增或修改的的代码前加上注释，规范如下：/* * 功能说明 * 修改者 修改|新增 日期 */例如：/* * 把密码进行md5加密 * 唐杰 新增 2008-07-29 */String mdtPwd=com.globalzt.framework.util.SecurityUtil.MD5(password);3.7 配置文件编写规范RichFaces、Spring、Struts2等框架或自定义的配置文件规范。l XXX配置文件规划。模块名配置文件名说明项目管理applicationContext-projectManagement.xml揭示板applicationContext-bbs.xmlQAapplicationContext-QA.xmlQCapplicationContext-QC.xml权限applicationContext-security.xmll 其他配置规范要求3.8 请求处理层编码规范JSF的ManagedBean或者Struts2的Action的编码规范l 类属性命名规则如果属性和Hibernate的pojo对应，则两者名称必须保持一直。l 其他编码规则，包括增删改查等函数命名规范，要求提示信息使用资源号等等。3.9 业务逻辑层编码规范Service类的编码规范，包括增删改查等函数命名规范3.10 DAO层编码规范DAO类的编码规范，包括增删改查等函数命名规范3.11 Model层编码规范Model层的编码规范3.12 异常规范异常处理的编码规范3.13 日志规范日志处理的编码规范3.14 事务规范事务处理的编码规范3.15 国际化及资源文件编码规范l 每个资源文件名称后面必须加上语言后缀。例：英文-“_en”，日文-“_ja”，中文-“_zh”l “页面显示”使用的资源文件放在JavaSource的每个子模块的resource目录下。例：com/user/customermanagement/resource/user_pertiescom/user/customermanagement/resource/user_pertiesl “页面显示”使用的共通的资源文件放在“/JavaSource/com/globalzt/项目名称/common/resource/”目录下l “提示信息”使用统一的资源，它们是：/JavaSource/com/globalzt/项目名称/common/resource/message_perties/JavaSource/com/globalzt/项目名称/common/resource/message_pertiesl “提示信息”资源文件里面的信息的name，使用model_xxxx的方式编写。其中，model是模块名称，xxxx是自己取的名称。例：customerManagement_saveSuccess=save successed！customerManagement_savefailed=save failed！customerManagement_canotDelete=you cant delete the customer！l “提示信息”全部已中文感叹号结束。例：customer_insert=新增客户出错！l 子文件架的命名方式使用首单词小写，之后每个单词首字母大写。4 前台页面规范4.1 HTML规范l 页面应该加上互动维客现阶段使用的XHTML1.0 Transitional标准：l CSS引用放在之中，不能放在中。l 建议JS的引用放在之后，如果页面中有调用js的函数，则放在之中。l 要求(X)HTML结构清晰。l 要求(X)HTML结构不要冗余。l (X)HTML代码不能和CSS混在一起。l (X)HTML代码不能和大量JS代码混在一起。l 页面兼容IE6、IE7、firefox等多种浏览器。l 重要模块和复杂页面必须加上页面注释4.2 JSP规范l Jsp代码中，页面连接跳转代码，URL地址必须严格区分大小写。l Jsp页面上所有引用外部文件的路径，或者跳转的url路径，中不能直接写web根名称。即：“/应用名称/css/main.css”，这种写法是错误的。正确写法：“/css/main.css”“/demo/test.jsf”“test.jsf”不推荐使用“.”打头的写法。如：“./demo/test.jsf”l JSP文件头部写如下内容，统一使用UTF-8编码方式。l JSP文件中的引用标签库的prefix必须统一。l 样式文件的引用，应该在标签库引用之后。以下跟自己项目框架有关的规范l 国际化资源引用规范l 页面效验规范l 页面消息提示编码规范4.3 JavaScript编码规范4.3.1 缩进所有JS代码缩进时候请采用Tab缩进，而不是空格缩进。4.3.2 变量规范l 要求变量使用前必须声明。示例：var myName;var tValue=document.getElementById(“myText”).value;l 第一个字母小写，之后每个单词间的首字母大写。例如：userName，password等l 全局变量，尽量采用大写字母，单词之间用下划线分隔。例如：MIN_BALANCE, DEFAULT_DATEl 避免使用下划线（除全局变量）l 避免使用类似的名字，或者仅仅是大小写不同的名字l 如果变量是集合，则变量名应用复数。例如：int students;4.3.3 函数规范l 函数名称第一个字母小写，之后每个单词间的首字母大写。l 函数中的所有语句必须换行，不允许多条语句连成一排。4.3.4 注释规范l JavaScript文件头注释格式如下：/* * js文件的说明 * Copyright (c) 2008 * 公司名称 * author 创建者 时间 * version 1.0 */示例：/* * 公共函数js文件 * author 唐杰 2008-07-24 * version 1.0 */l 函数注释注释格式/* * 函数功能解释 * param 参数名称1 参数解释 * param 参数名称2 参数解释 * return 返回值解释 * 创建者 创建时间 * 修改者 修改时间 修改内容 */示例：/* * 根据用户名查询一个用户 * param userName 用户名称 * return 用户对象 * 唐杰 2008-07-23 * 何刚 修改 2008-07-24 增加MD5加密算法 */4.3.5 变量注释变量的注释使用/，并写在变量申明的上方或者后方。例如：/用户名var userName;4.3.6 程序代码片断注释程序代码段的注释可以使用/* */和/两种形式，请自行选择。例如：/获取用户文本框的值var userName =document.getElementById(“userNameText”).value;4.3.7 修改程序代码的注释修改别人的代码或者在别人函数里新增代码，需要在自己新增或修改的的代码前加上注释，规范如下：/* * 功能说明 * 修改者 修改|新增 日期 */4.3.8 JS文件规划l JavaScript程序应独立保存在后缀名为.js的文件中。l JavaScript的文件摆目录遵循“7.1文件目录规划”。l JavaScript文件目录下增加的子目录，请按模块或者按功能划分，不要随意增加。4.3.9 JS文件引用l Js文件的引用，不要使用import的方式，应该使用的方式。l Js文件的引用应尽量放到body的后面。这样可以减少因为载入script而造成其他页面内容载入也被延迟的问题。4.3.10 其他规范l JS文件压缩一般情况下，在发布时，要求js文件必须要压缩已减少下载大小。l 尽量不使用eval4.4 CSS样式规范4.4.1 Css编码书写规范l 常用类/ID命名规范尽量以常见英文单词为准，做到通俗易懂，多个单词之间用“-”分隔。例如：页面结构容器: page_margins页头：header 页面主体：main 页尾：footer 导航：nav 侧栏：sidebar 栏目：col 页面外围控制整体布局宽度：page 左右中：left right center导航导航：nav 主导航：main_nav 子导航：sub_nav 顶导航：top_nav 边导航：sidebar 左导航：left_sidebar 右导航：right_sidebar 标题: title 摘要: summary 功能标志：logo 广告：banner 登陆：login 登录条：loginbar 注册：regsiter 搜索：search 功能区：shop 标题：title 加入：join_us 状态：status 按钮：btn 滚动：scroll 标签页：tab 文章列表：list 提示信息：msg 当前的: current 小技巧：tips 图标: icon 注释：note 指南：guild 服务：service 热点：hot 新闻：news 下载：download 投票：vote 合作伙伴：partner 友情链接：link 版权：copyrightl 样式属性缩进请采用Tab缩进，而不是用空格。l 不允许样式直接定义在标签中标签中不允许用style这个属性定义样式。l 行注释和块注释行注释直接写于属性值后面。块注释写在样式类前面。例如：/*搜索条样式*/.searchborder:1px solid #fff; /*边框*/background:url(./images/icon.gif) no-report #333; /*背景*/l 不同类有相同属性及属性值的缩写对两个不同的类，但是其中有部分相同甚至是全部相同的属性及属性值时，应对其加以合并缩写，特别是当有多个不同的类而有相同的属性及属性值时，合并缩写可以减少代码量并易于控制。例如：#main_menu background:url(./images/bg.gif);border:1px solid #333;width:100%;height:30px;overflow:hidden;#sub_menu background:url(./images/bg.gif);border:1px solid #333;width:100%;height:20px;overflow:hidden;两个不同类的属性值有重复之处，刚可以缩写为：#main_menu,#sub_menu background:url(./images/bg.gif);border:1px solid #333;width:100%;overflow:hidden;#main_menu height:30px;#sub_menu height:20px;l 同一类的属性缩写对同一类中margin、padding、border、background、颜色值等属性进行缩写。例如：.btn margin-top:10px;margin-right:8px;margin-bottom:12px;margin-left:5px;padding-top:10px;padding-right:8px;padding-bottom:12px;padding-left:8px;则可缩写为：.btn margin:10px 8px 12px 5px;padding:10px 8px 12px 5px;4.4.2 Css在Jsp中的使用l Css文件命名以常见英文单词并以全部小写为准。例如：主要样式：base.css框架样式：layout.css补丁样式：patches.cssl 公共Css存放对框架的css样式，放在WebContentcsslayout.css文件中。整个公用样式或者多个页面共用样式，放在WebContentcssbase.css文件中。l Css文件目录页面共同样式文件应放在WebContentcss目录下。其它模块个性化样式如果比较少，可以放到head中，如果样式过大，超过2kb，应在WebContentcss目录下，以自己的模块名建立新的子目录，并在自己的模块目录下建立css文件，存放自己的模块css样式。l Css样式文件引用css文件的引用应放在head标签中，在style和script标签之前。使用以下语句：语句引用。注：XXX是引用的css文件的路径和样式文件名4.4.3 Yaml框架在Jsp页面的使用请参照：YAML CSS框架使用手册V1.0.doc 。4.4.4 其它规范l Css文件压缩。一般情况下，在发布时，要求Css文件必须要压缩来减少下载大小。5 自定义(标记)控件使用规范自定义标记、JS控件等的使用规范6 公共函数、程序6.1 Java公共函数列出Java程序中的公共函数及其说明6.2 JavaScript公共函数列出Javascript中的公共函数及其说明6.3 公共模块调用规范公共模块的调用规范，如：人员选择模块6.4 其他公共说明其他公共说明规范7 文件部署规范7.1 文件目录规划l 目录清单名称位置说明源代码/Promana/JavaSource源码子目录规划参见“包命名规范”web根目录/Promana/WebContent配置文件目录/Promana/WebContent/WEB-INF主要指spring、jsf的配置文件引用包目录/Promana/WebContent/WEB-INF/lib样式目录/Promana/WebContent/cssjavascript目录/Promana/WebContent/js图片目录/Promana/WebContent/imagejsp目录/Promana/WebContent/jspl 样式、js、图片目录下，可根据需要自行增加子目录，共同的都放到样式、js、图片各自的根目录下。例如：样式的根目录：“/Promana/WebContent/css”l jsp目录下面的子目录结构要求按照“模块和其子模块”层层下去。l 公共页面放置地址。l 范例页面文件放置地址。7.2 一般文件命名规范没有特别说明的文件命名方式按照：首个单词全部小写，之后每个单词的首字母大写。7.3 jsp文件命名规范l jsp文件的命名规则为AAXXXXCCC.jsp其中：AA为大模块缩写，如果只有一个模块，则AA可以省略。AA要求全部字母大写，长度建议在23个字符之间。XXXX为具体的业务模块名称，首字母大写，之后每个单词之间首字母大写。CCC是操作类型，具体类型包括：AddNew、Del、Update、Query、List几种类型。所有操作类型的首字母大写。如果不属于以上4种操作类型的jsp页面，可以自行命名操作类型。例如：MSCustomerManagementAddNew.jsp、MSCustomerManagementUpdate.jsp8 SEO优化规范8.1 目录结构和URLl 目录和访问层次网站的访问层次尽量不要超过三层，超过三层则不容易被搜索引擎收录。(google三层，百渡可以到5层)如：我们网站首页是第一层，点击首页连接跳转后的页面是第二层，再次点击连接跳转后的页面是第三层。l 动态 URL网站动态生成的URL常包含 “?”、“= ”、 “%”，以及“&”、“$”等特殊符号。如果能动态生成URL则不要动态生成，因为这些符号严重影响搜索排名。如：/messages.php?id=2&type=5一些动态url可以通过技术手段将他们静态化。8.2 导航优化l 主导航醒目清晰主栏目必须在网站首页第一屏的醒目位置体现，并最好采用文本链接而不是图片。l 层级导