项目开发及编码规范.doc

项目开发规范文档修订历史记录日 期版 本说 明作 者2009-12-25V1.0初稿1.简介1.1目的1、用于规范指导开发组进行开发2、便于成员间的沟通与交流。3、有助于项目质量和稳定。4、为后期维护提供支持2. 项目开发流程项目开发过程归纳分为以下步骤：1. 建立SVN项目版本控制。包括文档，源码，Lib包等。2. 了解需求，并对需求文档的书写。(见文档结构规则附录)。3. 详细设计文档。(见文档结构规则附录)。 3.1 功能模块设计，重要模块的算法设计。 3.2 数据库设计等。 3.3 根据需求定义开发平台及环境。4. 编码。 4.1 搭建开发平台，配置开发环境。 4.1 编码。 4.2 单元测试案例。5. 书写软件安装手册文件，数据库脚本文件，以及注意事项(release notes)。6. 交互测试组测试。根据测试组测试结果是否回归第4步（测试回归最好不要超过2次）。7. 测试通过，交付上线使用。 7.1 维护手册 7.2 使用手册3. 代码规范3.1 Java 代码规范3.1.1 Java类名类名可由：英文字母，数字，下划线组成。（数字，下划线不能够开头）类名由一个或者多个单词组成。单词通常要求简洁明了达意。能够通过类名能够大致了解此类的作用和用途。类名要求首字母大写，多个单词组成类名时，单词的首字母要求大写。建议：类名不要过于简单或者太长。可以对单词采用简化的名称：入： Number 简化为：num 。3.1.2 Java类结构类仅作为数据结构，没有行为，他封装了一组或者相似的一些行为方法。所以一个类尽量功能单一，或者功能类似共有行为的。一个类不要过于庞大。通常情况下：一般逻辑类中应该有构造方法和main方法，main方法中应该有测试代码。每个类应该有 toString() 方法。 包和引入语句在多数Java源文件中，第一个非注释行是包语句。在它之后可以跟引入语句。报名的定义全部是小写字母。具体定义依据项目而定。引入包时候，同一类型的归纳到一块，用空行隔开。例如：import java.util.ArrayList;import java.util.List;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import com.ericsson.omc.persistence.etl.ImsEtlTaskDao;import com.ericsson.omc.persistence.mapping.nemsg.Counter;import com.ericsson.omc.persistence.mapping.nemsg.EtlTask;import com.ericsson.omc.persistence.mapping.nemsg.Indicator;import com.ericsson.omc.persistence.mapping.nemsg.Node; 类注释Java类开头应该有相应的注释：类版本描述，作者签名，日期时间，公司备注，类的功能作用相关描述等。（详细查看：注释） 类成员变量a) 类变量要求放在类的开始声明。一行声明一个。b) 变量名称首字母要求小写。其他命名规则类似与类名。c) static , final 类型的变量，字母要求全部大写。d) 尽量在声明局部变量的同时初始化。e) 避免局部变量和成员变量同名，覆盖了成员变量。f) 尽量变量私有化，缩小变量的作用域。 类成员方法a) 方法名命名规则类似于成员变量命名规则。b) 成员方法尽量私有化。d) 方法与方法之间空一行分割，提高可读性。c) 方法尽可能有注释：（详细查看：注释）e) 方法尽可能尽早返回，结束。3.1.3 Java语句 缩进排版a) 4个空格(一个Tab建)常被作为缩进排版的一个单位。子模块应该和父模块保持一个缩进单位。b) 尽量避免一行的长度超过80个字符.c) 换行：当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：- 在一个逗号后面断开- 在一个操作符前面断开- 宁可选择较高级别(higher-level)的断开，而非较低级别(lower-level)的断开- 新的一行应该与上一行同一级别表达式的开头处对齐- 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。 如： someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 注释Java程序有两类注释：实现注释(implementation comments)和文档注释(document comments)。实现注释是使用/*.*/和/界定的注释。文档注释(被称为doc comments)是Java独有的，并由/*.*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以描述实现的细节，流程，和难点的描述。良好的实现注释有助于自己和别人易于读懂代码。文档注释它可以被那些手头没有源码的开发人员了解接口功能等。频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下是否可以重新设计该模块的代码结构或者逻辑，使其更清晰，而避免使用注释提醒该模块的实现，这样往往都能够提高代码质量。注释应被用来给出代码的总括，良好的代码里应该有大量的注释。当然也要避免代码已经提供清晰明了，显而易见注释。注释的格式：程序可以有4种实现注释的风格：块 、单行 、尾端 和行末 。分别由：/* notice */ 块/* notice */ 单行/* notice */ 尾端/ 行末注释要求：l 无论是用户端表示层程序还是组件程序，注释必不可少。l 要求能占程序总量的10%以上。l 注释必须在程序改变时实时更新。l 简单明了，确保任何程序员都可以读懂。l 注释一般应写在代码之前，并与代码分开不同的行；但对于说明变量含义的注释，一般应写在变量说明的同行的行末，并且在各行间保持对齐；l 如果可能，尽量使用单行注释 /。l 对于代码维护，应在过程或方法中记录相应修改的作者、时间，并在具体修改的位置用特殊的标签注明（标签一般应包含修改人的名字汉语拼音或拼音简写、日期戳和可选的修改项目名字）。例子如下：/modify by XXX 2006-5-15 修改内容的文字说明./modify by XXX2006-5-15 end一 实现注释：实现注释应该在构建内部必要的过程中加上必要的注释，包括：功能描述、参数说明、返回值说明、最后更新作者(如果有改动)、最后更新日期(如果有改动)。重要变量应该在行末使用”/”加上注释。重要的，难点流程，应该加上行注释，或者尾端，行末注释。 二 JavaDoc注释：为规范、方便生成统一的程序文档，应在代码注释中遵循JavaDoc的注释规范（在Eclipse中输入“/*回车”，会自动根据你的java方法参数，返回类型等填入注释项。）类注释应与JavaDoc中的对应：模块名称： See功能描述： Todo作者： Author版本： Version公司版权信息：Copyright ? 2009 LinkCm Co. Ltd. All right reserved./* * 对系统规范化的异常处理。包含各种异常编码，标准出错提示与日志的产生和管理。 * * 异常类型ID * 1-49 ：系统内部异常 标准处理：写日志，向客户端抛出CustomException异常 * 50-99 ：用户界面异常 标准处理：写日志，向客户端抛出对应的自定义异常 * 100以上：扩展异常 * * 注意：写日志时应使用 getSysMsg() 获得对应的异常日志记录串；向用户端抛出的 * 异常则在 getUserMsg() 中携带应在界面上显示的信息串 * * since 2001-12-18 * author lijun * version 1.0* Copyright ? 2009 LinkCm Co. Ltd. All right reserved.*/ * */过程和方法注释与JavaDoc中对应：功能描述： Method Comments参数说明： Parameter Comments返回值说明： Returns最后更新作者： 如有改动，自己添加 /* * 初始化方法，在这里初始化所有用户公用的变量， * 这里简单地将工作交给父类处理。 * param config ServletConfig对象，包含Servlet初始化的参数。 * throws ServletException 初始化可能产生ServletException异常。 * return */最后更新日期： 如有改动，自己添加 语句示例：a) 简单语句每行至多包含一条语句，例如： argv+; / Correct argc-; / Correct argv+; argc-; / AVOID!b) 复杂语句复合语句是包含在大括号中的语句序列，形如 语句 。例如下面各段。- 被括其中的语句应该较之复合语句缩进一个层次- 左大括号应位于复合语句起始行的行尾；右大括号应另起一行并与复合语句首行对齐。- 大括号可以被用于所有语句，包括单个语句，只要这些语句是诸如if-else或for控制结构的一部分。这样便于添加语句而无需担心由于忘了加括号而引入bug。 c) for 语句for语句中，避免吧运算表达式写入for中例如：Object array = new Object1000;for( int i = 0; i array.length; i+)/ do somethine此时在for循环中将会重复计数 array的长度， 优化后应该是：Object array = new Object1000;Int len = array.length;for( int i = 0; i len; i+)/ do somethined) try catch 语句一个try-catch语句应该具有如下格式： try statements; catch (ExceptionClass e) statements; 一个try-catch语句后面也可能跟着一个finally语句，不论try代码块是否顺利执行完，它都会被执行。 try statements; catch (ExceptionClass e) statements; finally statements; 对一些数据库的连接，io访问等，尽量使用finally 块， 在finally块中关闭开启的资源。e) return 语句如： if (booleanExpression) return true; else return false; 应该改为下面方式更加简洁： if (booleanExpression) return true; return false;f) ： if(!(block_id = unblks)，不如写成if(block_id = actblks) | (block_id = actblks | block_id = actblks) | (block_id desc；information - info；address - addr等 （oracle限制表名超过30个字符）3.3.2 表字段名命名规则 字段名为小写 字段名为有意义的单词，或单词的缩写 如果字段由几个单词组成，则单词间用下划线(_)分割，如client_id，post_code等 字段名限制在30个字符内。当字段名超过30字符时，可用缩写来减少字段名的长度，如description - desc；information - info；address - addr等 3.3.3 索引命名规则 索引须按照IDX_table_,其中是建立索引的表名，是建立索引的字段名 索引名限制在30个字符内。当索引名超过30字符时，可用缩写来减少索引名的长度，如description - desc；information - info；address - addr等 3.3.4主建、外键命名规则 主键按照PK_的规则命名，其中为数据库表名 唯一键按照UK_的规则命名，其中为数据块表名，为字段名 外键按照FK_的规则命名，其中为父表名，为子表名，为序列号 3.4 Java命名规则命名规范使程序更易读，从而更易于理解。它们也可以提供一些有关标识符功能的信息，以助于理解代码，例如，不论它是一个常量，包，还是类。标识符类型命名规则例子前提* 尽量使用完整的英文描述符，采用适用于该领域的术语 * 采用大小写混合使名字可读 * 尽量少用缩写，但如也可以使用公共常用的缩略语，如： HTML， IO。 * 避免使用长的名字（小于 15 个字母是个好主意） * 避免使用类似的名字，或者仅仅是大小写不同的名字、包(Packages)一 个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com，edu，gov，mil，net，org。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部 门(department)，项目(project)，机器(machine)，或注册名(login names)。.etl类(Classes)命名规则：类名是个一名词，采用大小写混合的方式，每个单词的首字母大写。尽量使你的类名简洁而富于描述。使用完整单词，避免缩写词(除非该缩写词被更广泛使用，像URL，HTML)class Raster;class ImageSprite;接口(Interfaces)命名规则：大小写规则与类名相似interface RasterDelegate;interface Storing;方法(Methods)方法名是一个动词，采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。run();runFast();getBackground();变量(Variables)除了变量名外，所有实例，包括类，类常量，均采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。临时变量通常被取名为i，j，k，m和n，它们一般用于整型；c，d，e，它们一般用于字符型。char c;int i;float myWidth;实例变量(Instance Variables)大小写规则和变量名相似，除了前面需要一个下划线int _employeeId;String _name;Customer _customer;常量(Constants)类常量和ANSI常量的声明，应该全部大写，单词间用下划线隔开。(尽量避免ANSI常量，容易引起错误)static final int MIN_WIDTH = 4;static final int MAX_WIDTH = 999;static final int GET_THE_CPU = 1;4. 开发平台及工具。4.1平台项目定义具体开发平台和工具视不同的项目需求而定。同一项目组的开发平台要求尽量统一。对应J2EE开发平台定义如下列表：环境资源项目名称版 本说 明操作系统Windows XPJDKIDEEclipse开源框架及工具应用服务器Tomcat版本控制SVN其他资源4.1版本控制工具在没有特殊要求外，要求使用TortoiseSVN 工具。TortoiseSVN 是 Subversion 版本控制系统的一个免费开源客户端，可以超越时间的管理文件和目录。文件保存在中央版本库，除了能记住文件和目录的每次修改以外，版本库非常像普通的文件服务器。你可以将文件恢复到过去的版本，并且可以通过检查历史知道数据做了哪些修改，谁做的修改。4.1.1 SVN使用方式： 一：一是简单使用，即建立一个主干项目目录，各个开发成员同时使用这个主干目录进行直接修改与更新。二：二是建立项目主干，和各个开发成员的分支目录。(1). 各开发成员建立自己的分支，并在此分支上开发；(1). 各开发成员把分支合并到主干上并形成较为稳定的版本；(1). 各个成员重新从主干上建立新的分支，在此分支上开发(即回到第一步)(1). 循环往复，直到工程结束。目前使用是的一种方式。4.1.1 SVN文件提交规