开发规范文档V1.0.doc

烟台海涛网络科技有限公司 开发规范V2.0开发规范V2.0编写日期：2015.03.15烟台海涛网络科技有限公司前言为什么要有开发规范开发规范对团队开发而言尤为重要。 一个软件的生命周期中，80%的花费在于维护 几乎没有任何一个软件在整个生命周期中均由最初的开发人员来维护 编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新的代码 开发工具的统一是团队开发的基础 不同的开发工具版本，开发过程中出现的错误可能不一致开发规范定义目标研发时应该强调的一个重要方面是程序的易读性，在保证软件速度等性能指标能满足用户需求的情况下，能让其他程序员容易读懂你所编写的程序。所有开发人员都遵循统一的、鲜明的一套编程风格，可以让协同者、后继者和自己一目了然，在很短的时间内看清楚程序结构，理解设计的思路，大大提高代码的可读性、可重用性、程序健壮性、可移植性、可维护性。一、 开发工具安装规范开发工具存放推荐使用单独文件夹存放开发工具，此文件夹不可包含中文、空格如：E:Tools1 JDK安装与配置JDK版本选择公司使用版本 jdk-6u45-windows-x64.exeJDK的安装配置JDK安装的位置，如E:ToolsJavajdk1.6.0_45添加环境变量：【JAVA_HOME】E:ToolsJava jdk1.6.0_45【PATH】 注：一般情况下需要在添加前给Path变量上一路径加上 ” ; ” 号%JAVA_HOME%bin;.2.2.测试JDK安装成功在cmd命令提示符中执行：C:Documents and SettingsAdministratorjava -versionjava version 1.6.0_45Java(TM) SE Runtime Environment (build 1.6.0_16-b01)Java HotSpot(TM) Client VM (build 14.2-b01, mixed mode, sharing)2 Maven安装与配置Maven安装与配置解压Maven至E:Toolsmaven-3.2.5，并在目录中创建repository文件夹。添加环境变量：【MAVEN_HOME】E:Toolsmaven-3.2.5【PATH】 注：一般情况下需要在添加前给Path变量上一路径加上 ” ; ” 号% MAVEN _HOME%bin;测试Maven安装成功在cmd命令提示符中执行：C:UsersAdministratormvn -versionApache Maven 3.2.5 (12a6b3acb947671f09b81f49094c53f426d8cea1; 2014-12-15T01:29:23+08:00)Maven home: E:Toolsmaven-3.2.5bin.Java version: 1.6.0_45, vendor: Sun Microsystems Inc.Java home: E:ToolsJavajdk1.6.0_45jreDefault locale: zh_CN, platform encoding: GBKOS name: windows 7, version: 6.1, arch: amd64, family: windows配置Maven资源库1. 打开maven根目录的conf文件夹，编译settings.xml2. 全文搜索localRepository节点，在注释外添加一下内容Maven根目录/repository在红字处将你的maven中的repository设置为你自己的目录。如：E:Toolsmaven-3.2.5repository3 Eclipse安装与配置1.2.3.Eclipse版本选择使用Dorado_Eclipse3.7或是eclipse-jee-indigo（3.7）.1.Eclipse安装配置整个目录禁止中文空格安装Eclipse到某个目录，如：E:ToolsDorado_eclipseeclipse启动Eclipse，选择工作空间：E:ToolsDorado_eclipseworkspaces存放Tomcat到某个目录，如：E:ToolsDorado_eclipseTomcat7Eclipse配置1 修改JDK配置Window Preferences Java Installed JREsJRE home: E:ToolsJavajdk1.6.0_45JRE name: jdk1.6将jdk1.6.0_45统一修改为jdk1.62 修改项目统一编码Window Preferences General WorkspaceText file encoding - Other - UTF-83 关闭验证Window Preferences ValidationBuild下的复选框全部取消4 取消Eclipse的拼写检查Window Preferences General Editors Text Editors Spelling取消Enable spell checking复选框5 导入注释模板Window Preferences Java Code Style Code Templates在SVN下载codetemplates.xml文件 - Import - 修改每个注释类型的author为自己名字全拼 如：author lindapeng6 启用代码自动提示具体视个人开发习惯而定Window Preferences Java Editor Content Assist修改Auto activation triggers for Java -.abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ(,7 Tomcat内存大小配置配置好Eclipse的环境并安装好Tomcat后，先启动一下Tomcat程序Run - Configurations - Arguments - VM arguments添加：-Xms256M -Xmx512M -XX:PermSize=128M -XX:MaxPermSize=512MEclipse插件1 Jad反编译插件安装（Maven用户不推荐安装）从SVN获取 jad.exe；net.sf.jadclipse_3.3.0.jar两个文件将jad.exe放到：E:ToolsJavajdk1.6.0_45bin将net.sf.jadclipse_3.3.0.jar放到：E:Toolsdorado_eclipseeclipsedropins重启EclipseWindow Preferences Java Editor JadClipsePath to decompiler: E:ToolsJavajdk1.6.0_45binjad.exeDirectory for temporary files: E:Toolsdorado_eclipseeclipse测试：随意打开一个工程，打开Jar包中的Class文件，判断是否反编译成功2 m2eclipse插件安装（Maven）从SVN获取eclipse-maven3-plugin.zip将压缩包中的features和plugins中的内容复制到eclipse项目的文件夹中重启eclipsel Window Maven去掉 Download repository index updates on startupl 打开eclipse的配置：Window Preferences Maven Installations点击Add选择你自己本地的Maven根目录（E:Toolsmaven-3.2.5）l Window Preferences Maven User Settings点击Browse. 选择本地Maven根目录/conf/ settings.xml 文件如：E:Toolsmaven-3.2.5confsettings.xmlEclipse常用快捷键快捷键说明Ctrl+1快速修复，通常在错误代码上使用。Ctrl+O显示类中方法、属性和大纲Alt+/代码提示Ctrl+/单行注释Ctrl+Shift+C多行注释Ctrl+D删除当前行Ctrl+M窗口最大化、最小化切换Ctrl+T快速显示当前类的继承结构Ctrl+L快速定位到某一行Ctrl+Q快速定位到最后一次编辑的位置Ctrl+H全局搜索Ctrl+W关闭当前编辑器Ctrl+E快速显示文件下拉列表Ctrl+Shift+R快速查找资源、文件Ctrl+Shift+F格式化某段代码（可选中、可全局）Ctrl+Shift+O快速导包、移包Ctrl+K、Ctrl+Shift+K快速向下、向上查找选中内容Shift +Enter、Ctrl+Shift+ EnterShift+Enter在当前行之下创建一个空白行Ctrl+Shift+Enter则在当前行之前插入空白行。F4查看类结构Ctrl+Shift+（ ）复制当前行到（下 上）一行Alt+（ ）当前行和（下 上）一行相互交换位置Alt+Shift+M抽取方法，选中某代码Alt+Shift+C修改函数结构，如有多个方法调用只修改一次Alt+Shift+R统一修改所有变量名Alt+Shift+Z重构Alt+Shift+L抽取本地变量，选中1使用自动生成int name=1二、 编码规范标识符的命名力求做到统一、达意和简洁。1 统一统一是指，对于同一个概念，在程序中用同一种表示方法，比如对于供应商，既可以用supplier，也可以用provider，但是我们只能选定一个使用。如果对同一概念有不同的表示方法，会使代码混乱难以理解。即使不能取得好的名称，但是只要统一，阅读起来也不会太困难，因为阅读者只要理解一次。2 达意达意是指，标识符能准确的表达出它所代表的意义，比如：newSupplier,findOrderById等；而supplier1,service2等则不是好的命名方式。准确有两成含义，一是正确，二是丰富。如果给一个代表供应商的变量起名是order，显然没有正确表达。同样的，supplier1,远没有targetSupplier意义丰富。3 简洁简洁是指，在统一和达意的前提下，用尽量少的标识符。如果不能达意，宁愿不要简洁。比如：theOrderNameOfTheTargetSupplierWhichIsTransfered太长，transferedTargetSupplierOrderName则较好，但是transTgtSplOrdNm就不好了。省略元音的缩写方式不要使用，我们的英语往往还没有好到看得懂奇怪的缩写。4 驼峰法则Java中，除了包名，静态常量等特殊情况，大部分情况下标识符使用驼峰法则，即单词之间不使用特殊符号分割，而是通过首字母大写来分割。比如:supplierName,addNewContract，而不是supplier_name,add_new_contract1 目录结构JAVA服务端java服务端的开发源包以maven结构为主，分为1. src/main/java（开发包）l common：框架公共目录、公共源文件【开发人员禁止编辑】l utils：公共工具类，开发人员只需使用【开发人员禁止编辑】l adms（各项目名）：产品包，开发人员的主要工作目录2. src/main/resources（开发资源包）【开发人员禁止编辑】3. src/test/java（测试包）【暂不使用】4. src/test/resources（测试资源包）【暂不使用】Web前端Web前端开发主要分为四个目录，分别是app、css、images、js目录命名规范：所有命名必须小写英文（或缩写），不能大写或中文，不能应用特殊字符。1. app（UI目录）app目录下每个功能模块建立一个目录，目录的命名根据模块的语议来定义，如果单个词能定义的就用单个英文词（或缩写）或全拼命名规范app目录中包含一个common目录，此目录是存放公共信息页面的目录，例如：分页信息页面存放此处，那么需要分页的页面引用该目录的分页页面即可。【开发人员禁止编辑】2. css（样式目录）存放公共样式信息的目录，例如：style全局样式，jquery-ui的样式，树形样式等。【开发人员禁止编辑】3. images（图片目录）images存入图片的目录，各级目录中存放相应的图片。【开发人员禁止编辑】4. js（UI前端的脚本目录）js目录存入前端页面中应用的js脚本文件，js目录中会包含多级子目录，子目录以模块名命名。js目录中的common目录存放公用脚本文件，包括jQuery文件和自定义脚本文件。【开发人员禁止编辑】2 命名规范包命名1. 所有包命名必须全部采用小写英文字母。2. 包名开头一般采用公司网站域名，如com.ht.，projectName为项目名称3. 在包名开头之后的一个单词为模块名称，如com.ht.ourally.，module为模块名称4. 应用系统分层，Dao（数据访问层）、Service（业务逻辑层）、Web（页面控制层，其中包含Action、Dorado视图、Vo对象）Dao层：com.ht.ourally.base.daocom.ht.ourally.base.dao.implService层：com.ht.ourally.base.servicecom.ht.ourally.base.service.implWeb层：com.ht.ourally.base.web.actioncom.ht.ourally.base.web.vo com.ht.ourally.base.web.view类命名1. Action命名：模块名+Action，如用户管理 UserAction.java2. Dao命名：接口以I开头，如用户管理IUserDao.java，实现类以Impl结尾如UserDaoImpl.java3. Model命名：以映射文件生成为主，一般为User.java4. Service命名：接口以I开头，如IUserService.java，实现类以Impl结尾如UserServiceImpl.java5. 后缀，类名不同的后缀往往表达额外的意思，参考下表：后缀名意义例子Service表示这个类是服务类，里面包含了提供给其类的业务方法IUserServiceDao表示这个类封装了数据访问的方法IUserDaoImpl这个类是接口实现类UserServiceImplAction直接处理页面请求，为页面层级提供数据UserActionVoVo是Po演变出的一种类模式，Vo通常用于业务层之间的数据传递或封装UserVoListener响应某种事件的类ViewListenerFilter过滤器LoginFilterFactory生成某种对象工厂的类SessionFactoryTask某种按时间运行的任务ClearTask方法命名1. 方法的命名采用驼峰命名法，动词在前。动词前缀表达含义如下：前缀名意义例子find查询findOrderById()update更新updateOrderById()add添加addOrder()delete删除deleteOrder()show为显示某页面的执行方法showStoreList()audDorado特有方法前缀，表示增改删audOrder()init初始化，创建，暗示新创建的对象属于某个集合initObjectPool()destroy销毁，暗示会做些诸如释放资源的特殊动作destroyObjectPool()open打开openConnection()close关闭closeConnection()write写入writeUserName()read读取readUserName()get获取getName()set设置setName()do执行某个过程或流程doOrderCancel()注：对于特殊的方法，需要使用指定参数（如：Id和Name），方法名使用关键字 “By” 做标示，如：findOrderById(String id);findOrderByIdAndName(String id,String name);findUserByUserName(String userName);常量命名常量的名字应该都使用大写字母，并且指出该常量完整含义。如果一个常量名称由多个单词组成，则应该用下划线来分割这些单词。如：MAX_VALUE【开发人员禁止编辑】JSP命名/Dorado视图JSP命名应遵循页面内容或用途进行命名，首字母小写Dorado视图命名应遵循页面内容或用途进行命名，首字母大写查询列表：业务名称 + List，如：userList.jsp / UserList.view.xml增加功能：业务名称 + Add，如：userAdd.jsp / UserAdd.view.xml修改功能：业务名称 + Update，如：userUpdate.jsp / UserUpdate.view.xml树形功能：业务名称 + Tree，如：userTree.jsp / UserTree.view.xml其他功能：业务名称 + 动词，如：userHouseInto.jsp 客户迁入注：文件/视图的命名采用驼峰命名法，动词在后。动词后缀表达含义如下后缀名意义例子List列表视图orderList.jspAdd添加视图orderAdd.jspUpdate修改视图orderUpdate.view.xmlDetail详情视图orderDetail.view.xmlTree树视图orderTree.jspDorado控件命名Dorado的命名规范符合Java变量名规则，要采用有意义的命名方式，可以通过名字就能看出是一个什么样的控件，通常我们使用控件名称为前缀，如：dataSetUser、dataGridUser、buttonAdd可参考控件命名完整名称：/pages/viewpage.action?pageId=34275336 SpringMVC映射命名l 类映射命名为 /$moduleName/$functionName 如：RequestMapping(/base/dict) / 基础管理/字典功能l 方法映射命名为当前方法名称3 注释规范注释在我们日常开发过程中带来很大的便利性。对于类，主要着重要描述它的职责，即它能干什么，对于复杂的算法实现，应该使用内部实现注释，说明算法的主要思路，对于长方法，要让阅读代码的人比较容易的明白方法实现的主要流程。反之，对于一看就懂的方法，则不需要进行注释，比如get/set方法。注释放两张图片供大家参考声明一个普通的方法，并为其添加注释描述：调用该方法，鼠标移入方法名上查看注释内容一般原则1. 代码应该和注释保持同步。2. 注释应该增加代码的清