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

资料内容仅供您学习参考，如有不当或者侵权，请联系改正或者删除。

项目开发规范文档

修订历史记录
日 期
版 本
说 明
作 者
-12-25
V1.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 Object[1000];
for( int i = 0; i < array.length; i++){
// do somethine
}
此时在for循环中将会重复计数 array的长度, 优化后应该是:
Object[] array = new Object[1000];
Int len = array.length;
for( int i = 0; i < len; i++){
// do somethine
}

d) 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 < actblks) || !( block_id >= unblks)),
不如写成if((block_id >= actblks) || (block_id < unblks))
多加上括号, 增加易读性 也排除二义性:
if( block_id >= actblks || block_id < unblks )
比如写成: if( (block_id >= actblks) || (block_id < unblks) )

g) 空行, 空格

空行:
空行将逻辑相关的代码段分隔开, 以提高可读性。
下列情况应该总是使用两个空行:
- 一个源文件的两个片段(section)之间
- 类声明和接口声明之间
下列情况应该总是使用一个空行:
- 两个方法之间
- 方法内的局部变量和方法的第一条语句之间
- 块注释之前
- 一个方法内的两个逻辑段之间, 用以提高可读性

空格:
下列情况应该使用空格:
- 一个紧跟着括号的关键字应该被空格分开, 例如:
while (true) {
...
}
注意: 空格不应该置于方法名与其左括号之间。这将有助于区分关键字和方法调用。
- 空白应该位于参数列表中逗号的后面
- 所有的二元运算符, 除了".", 应该使用空格将之与操作数分开。一元操作符和操作数之间不因该加空格, 比如: 负号("-")、 自增("++")和自减("--")。例如:
a += c + d;
a = (a + b) / (c * d);

while (d++ = s++) {
n++;
}
printSize("size is " + foo + "\n");

- for语句中的表示式应该被空格分开, 例如:
for (expr1; expr2; expr3)

- 强制转型后应该跟一个空格, 例如:
myMethod((byte) aNum, (Object) x);
myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

3.2 Jsp, JavaScript 代码规范
3.2.1 Jsp文件
Jsp文件命名, 首字母要求小写, 名称能够用多个单词组成。每个单词组合时候首字母大写。
建议:
列表页面为: XXXList.jps
表单展示页面为: XXXView.jsp
表单修改页面为: XXXModify.jsp

Jsp文件的内容编码格式 和 文件本身的编码格式要求统一。具体视项目要求。
页面尽量使用同一种标签表示, 比如只使用struts标签, 或者JSTL标签。
3.2.2 JavaScript文件
JavaScript脚本尽量建立独立的以”js” 为后缀的独立文本文件。页面单独应用js文件即可。文件命名与jsp文件相同。文件本身的编码格式需要和整个项目文件编码一致。
一个js文件包含一个或者多个function函数。

3.3数据库对象定义规范
3.3.1 表名命名规则
· 数据库表的命名以是名词的复数形式且都为大写, 如ACCOUNT, INDICATOR_HISTORY等等
· 如果表名由几个单词组成, 则单词间用下划线("_")分割, 如 CURRENT_COUNTER等
· 表名尽量用全名
· 表名限制在30个字符内。当表的全名超过30字符时, 可用缩写来减少表名的长度, 如description -> 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__,其中lumn>为字段名
· 外键按照FK___的规则命名, 其中为父表名, 为子表名, 为序列号

3.4 Java命名规则

命名规范使程序更易读, 从而更易于理解。它们也能够提供一些有关标识符功能的信息, 以助于理解代码, 例如, 不论它是一个常量, 包, 还是类。
标识符类型
命名规则
例子
前提
* 尽量使用完整的英文描述符, 采用适用于该领域的术语
* 采用大小写混合使名字可读
* 尽量少用缩写, 但如也能够使用公共常见的缩略语, 如: HTML, IO。
* 避免使用长的名字( 小于 15 个字母是个好主意)
* 避免使用类似的名字, 或者仅仅是大小写不同的名字、

包(Packages)
一 个唯一包名的前缀总是全部小写的ASCII字母而且是一个顶级域名, 一般是com, edu, gov, mil, net, org。包名的后续部分根据不同机构各自内部的命名规范而不尽相同。这类命名规范可能以特定目录名的组成来区分部 门(department), 项目(project), 机器(machine), 或注册名(login names)。
com.sun.eng
com.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 XP

JDK

IDE
Eclipse

开源框架及工具

应用服务器
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 测试计划

。。。。

关于我们      便捷服务       自信AI       AI导航        抽奖活动©2010-2026 宁波自信网络信息技术有限公司  版权所有客服电话：[phone]  投诉电话：[phone]浙公网安备33021202000488号   浙ICP备2021020529号-1  |  浙B2-20240490  关注我们 ：