项目开发及编码规范样本.doc

资料内容仅供您学习参考，如有不当或者侵权，请联系改正或者删除。项目开发规范文档修订历史记录日 期版 本说 明作 者 -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() 方法。3.1.2.1 包和引入语句在多数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;3.1.2.2 类注释Java类开头应该有相应的注释: 类版本描述, 作者签名, 日期时间, 公司备注, 类的功能作用相关描述等。( 详细查看: 注释) 3.1.2.2 类成员变量a) 类变量要求放在类的开始声明。一行声明一个。b) 变量名称首字母要求小写。其它命名规则类似与类名。c) static , final 类型的变量, 字母要求全部大写。d) 尽量在声明局部变量的同时初始化。e) 避免局部变量和成员变量同名, 覆盖了成员变量。f) 尽量变量私有化, 缩小变量的作用域。3.1.2.3 类成员方法a) 方法名命名规则类似于成员变量命名规则。b) 成员方法尽量私有化。d) 方法与方法之间空一行分割, 提高可读性。c) 方法尽可能有注释: ( 详细查看: 注释) e) 方法尽可能尽早返回, 结束。3.1.3 Java语句3.1.3.1 缩进排版a) 4个空格(一个Tab建)常被作为缩进排版的一个单位。子模块应该和父模块保持一个缩进单位。b) 尽量避免一行的长度超过80个字符.c) 换行: 当一个表示式无法容纳在一行内时, 能够依据如下一般规则断开之: - 在一个逗号后面断开- 在一个操作符前面断开- 宁可选择较高级别(higher-level)的断开, 而非较低级别(lower-level)的断开- 新的一行应该与上一行同一级别表示式的开头处对齐- 如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边, 那就代之以缩进8个空格。 如: someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3);3.1.3.2 注释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 -5-15 修改内容的文字说明./modify by XXX -5-15 end一 实现注释: 实现注释应该在构建内部必要的过程中加上必要的注释, 包括: 功能描述、 参数说明、 返回值说明、 最后更新作者(如果有改动)、 最后更新日期(如果有改动)。重要变量应该在行末使用”/”加上注释。重要的, 难点流程, 应该加上行注释, 或者尾端, 行末注释。 二 JavaDoc注释: 为规范、 方便生成统一的程序文档, 应在代码注释中遵循JavaDoc的注释规范( 在Eclipse中输入”/*回车”, 会自动根据你的java方法参数, 返回类型等填入注释项。) 类注释应与JavaDoc中的对应: 模块名称: See功能描述: Todo作者: Author版本: Version公司版权信息: Copyright ? LinkCm Co. Ltd. All right reserved./* * 对系统规范化的异常处理。包含各种异常编码, 标准出错提示与日志的产生和管理。 * * 异常类型ID * 1-49 : 系统内部异常 标准处理: 写日志, 向客户端抛出CustomException异常 * 50-99 : 用户界面异常 标准处理: 写日志, 向客户端抛出对应的自定义异常 * 100以上: 扩展异常 * * 注意: 写日志时应使用 getSysMsg() 获得对应的异常日志记录串; 向用户端抛出的 * 异常则在 getUserMsg() 中携带应在界面上显示的信息串 * * since -12-18 * author lijun * version 1.0* Copyright ? LinkCm Co. Ltd. All right reserved.*/ * */过程和方法注释与JavaDoc中对应: 功能描述: Method Comments参数说明: Parameter Comments返回值说明: Returns最后更新作者: 如有改动, 自己添加 /* * 初始化方法, 在这里初始化所有用户公用的变量, * 这里简单地将工作交给父类处理。 * param config ServletConfig对象, 包含Servlet初始化的参数。 * throws ServletException 初始化可能产生ServletException异常。 * return */最后更新日期: 如有改动, 自己添加3.1.3.3 语句示例: 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)。com.sun.engcom.ericsson.omc.biz.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文件提交规则: 项目开发过程中, 文件及代码提交规则: a) 有变更代码及文档时候, 当天离开公司前要求提交到SVN。b) 提交代码时候, 要求代码能够编译经过。c) 提交代的码不能够影响这个项目的启动及运行。尽量避免本次的代码提交而影响到其它开发人员的工作或者功能模块的运转。d) 若需要更改别人的代码时候, 先Update, 然后更改, 然后commit ; 在commit时候, 尽量先Update动作, 避免冲突。5. 文档结构规则附录。5.1项目需求文档模板结构0. 文档版本历史标记。1 引言1.1 立项背景1.2 立项原因概述1.3 文档依据2. 项目概述2.1面向的用户人群2.2实现目标2.3 项目的图示结构。项目的总体结构图。2.4项目开发要求2.5 开发工具2.6 词汇表, 定义相关的词汇, 缩略语。3 功能模块1需求描述3.1 文字需求描述、 3.2 试图功能模块描述。4 功能模块2需求描述4.1 文字需求描述、 4.2 试图功能模块描述。5.1项目设计文档模板结构0. 文档版本历史标记。1 简介1.1 目的1.2 范围1.3 系统开发环境1.4 系统运行环境1.5词汇表, 定义相关的词汇, 缩略语。1.6 相关参考资料。2. 系统结构2.1 文字描述系统结构。2.2 图示系统结构。3. 功能模块1详细设计3.1 模块描述3.2 模块功能描述3.3 功能结构试图3.4 参考界面3.5 信息模型设计数据字典3.6 设计方法( 算法) 3.7 逻辑流程3.8 输入输出3.9 接口对内接口对外接口3.10 限制条件3.11 测试计划4. 功能模块2详细设计4.1 模块描述4.2 模块功能描述4.3 功能结构试图4.4 参考界面4.5 信息模型设计数据字典4.5 输入输出4.6 设计方法( 算法) 4.7 逻辑流程4.9 接口对内接口对外接口4.10 限制条件4.11 测试计划。