软件开发规范 v0.1
吴振亨@2002年12月25日
1 前言
为了使软件开发过程有章可循，保证软件质量，加强开发管理。
2 开发管理
项目进度周报表格如下：
项目编号：
汇报人：
汇报日期：
项目进度详细描述：
其他问题：
3 项目周期
司项目开发周期分为以下几个步骤：
步骤 说明 参与角色 生成文档或程序（打*号为可选）
可行性分析 对项目的技术，功能需求和市场进行调研和初步分析，确定是否需要立项开发。 部门主管核心技术员 可行性分析报告*技术调研报告*
立项 正式立项，由部门主管指定项目经理，项目经理制定初步计划。初步计划包括设计和开发时间的初步估算。 部门主管核心技术员 项目初步计划
需求分析 对项目进行详细的需求分析，编写需求分析文档。对于B/S结构软件系统需要制作静态演示页面。需求分析文档和静态演示页面需要通过部门主管审批才能够进行到下一个步骤 项目经理项目核心小组 需求分析文档静态演示页面项目计划修订版本
详细设计 根据需求分析对项目进行详细设计。详细设计以后，项目经理同部门主管一起指定项目小组开发成员。 项目经理项目核心小组 详细设计文档项目计划确定版本
开发 根据设计开发项目，由美工对操作界面进行美化。 项目经理项目开发员美工 项目计划修订版本*
测试 项目经理提交测试申请，由测试部门对项目进行测试。项目小组配合测试部门修改软件中的错误。 项目经理项目开发员测试部 测试申请测试计划测试报告
项目验收 项目验收归档 部门主管项目经理 项目所有文档和程序
4 命名规范
4.1 项目编号命名规范
待完善
4.2 文档命名规范
待完善
4.3 jsp/html命名规范
jsp与html文件名全部小写，并遵循如下的规范：
u 数据/内容显示页
名词，多个单词用下划线分隔，要求能说明显示内容的信息，为避免冲突，可加上 “_list”。例如：
new_message.html 或 my_file_list.jsp
u 操作处理页
命名格式：名词_下划线_动词，例如：file_delete.jsp。
u 含frame页面
<frameset>中<frame>的name属性命名的格式是①xxx._②xxx_③xxx
①xxx部分用来标识当前页面隶属于整个系统中的哪一功能模块。
如：属于ebwebmail则被表示为ebwebmail，其它情况依次类推。
②xxx部分标识当前页面所要完成的功能。
如：完成用户登录的功能则被标识为login，其它情况依次类推。
③xxx部分用来用来表示页面在浏览器窗口所处的位置。
处于浏览器窗口的顶部则标识为top，其它情况依次类推。
例如：ebwebmail_inbox_top.jsp
<frame> src属性相应的文件名根据情况建议在原命名规范上用下划线加上所处窗口的位置。
u javascript脚本方法
脚本函数都以①xxx_②xxx的方式命名。
①xxx对应页面隶属的模块。
②xxx表示函数所要实现的功能(动宾结构)，多个单词用下划线连接。
例如：ebwebmail_send_mail()
模块通用的脚本函数必须集合于一个js文件中，在页面上通过<script language=”javascript” src=”url”></script>形式导入。js文件名命名使用模块名，例如：ebwebmail.js。
如果项目已经提供了公共js脚本，则优先使用公共js脚本中提供的函数。
所有定义方法的<script>元素定义在<head></head>中或</body>后。
u javascript脚本内部变量与参数
单词之间用下划线分隔且全部小写，例如：
var file_size。
u <form>表单name属性
统一以“form_”开头，其后加该表单所需收集的信息的作用或动作，例如：form_file_upload 或 form_send_mail。
u 表单elements
表单element的名称以element需收集的信息标示命名，单词之间使用下划线分隔且全部小写，例如：
<input type=”text” name=”username”>
<input type=”radio” name=”file_type”>
<textarea name=”content” rows=”5” cols=”40”>
u cookie命名
命名格式：模块名_存储信息名词(多个单词用下划线分隔) ，全部大写，例如：EBWEBMAIL_SORT_TYPE。
u window.open中name参数的命名
javascript的window.open方法中有一个name的参数，浏览器约定同样的名字的窗口只能打开一个，如果程序间名字重复将相互冲突。如果不限制打开窗口数，可以指定‘’或“”（不是null），否则需要加上模块名，例如ebwebmail_viewmail。
4.4 数据库命名规范
数据库表命名均遵循以下规范：
模块名_存储信息名词(多个单词用下划线分隔)，全部小写，例如：ebwebmail_message。
数据库字段命名遵循以下规范：
存储信息名词(多个单词用下划线分隔)，全部小写，例如：message_id。
5 文档规范
1. 编写文档目前主要使用的工具是Word（项目计划文档例外，需要使用Project制作），辅助使用的工具有Visio，PowerPoint，ERWin等。
2. 文档务必保持段落格式整齐，文字字体，颜色，大小统一。
3. 如果需要摘引html页面中的内容，不能直接从html中粘贴过来（会在word文档中留下html格式），而必须先去除格式，例如：先粘贴到notepad中。
4. 务必注意中英文标点符号，文档正文一概使用中文标点符号。
5. 如果需要在文档中插图，不要使用word自带的绘图工具。可以选择使用PowerPoint或visio。使用PowerPoint，选择“插入”->“对象”->“Microsoft PowerPoint 幻灯片”。使用visio，需要另外建立visio文档，绘制完以后粘贴到word中。
6. 数据建模使用ERwin工具，文档中仅需要粘贴数据模型的逻辑视图（logical view），另外还要附上表结构描述。
7. 修改他人文档务必使用修订模式，以便保留备修改的内容。使用修订模式，选择“工具”->“修订”->“突出显示修订”，勾上“编辑时标记修订”。
附：一些模版
ü Java类设计(class documentation)
声明：
描述：
属性：
1. property_name
声明
说明
方法：
1. method_name
声明
说明
参数
返回值
异常
注：
方法声明中，如果遇到重载的方法，可以使用“|”表示可以接受不同类型的参数，例如：“String value | int value”；可以使用“[]”表示可选的参数，例如：“Object message[,Throwable t]”
ü Servlet设计(servlet document)
类名 接受参数列表 描述
ü 数据表设计(data modeling)
表名：some_table
说明：description
表结构：
字段名 类型 说明
6 代码规范
6.1 Java源代码规范
6.1.1 命名
u Package 的命名
Package 的名字应该都是由一个小写单词组成，例如：net.ebseries.modules。
此外，对于包名我们做如下约定：
1. 工具函数类包名前缀为.util
2. Servlet类包名前缀为.servlet
3. test case类包名前缀为.test
u Class 的命名
Class 的名字必须由大写字母开头而其他字母都小写的单词组成，例如：DataFile或InfoParser。
u Class 变量的命名
变量的名字必须用一个小写字母开头。后面的单词用大写字母开头，例如：debug 或 inputFileSize。
u Static Final 变量的命名
Static Final 变量的名字应该都大写，并且指出完整含义，例如：MAX_UPLOAD_FILE_SIZE=1024。
u 参数的命名
参数的名字必须和变量的命名规范一致。
u 数组的命名
数组应该总是用下面的方式来命名：
byte[] buffer;
而不是：
byte buffer[];
u 方法的参数
使用有意义的参数命名，如果可能的话，使用和要赋值的字段一样的名字：
SetCounter(int size)
{
this.size = size;
}
6.1.2 代码格式
u 文件头声明
源文件的头部需要一个history段，对于每次对源文件的重大改动，都需要在history段中注明。该段定义在package和import之间，例如：
／*****************************************************
* HISTORY
*
* 2002/01/29 Biz 创建文件
*
* 2002/02/19 kevin 增加新功能
*
*******************************************************/
u import顺序
import包按一下顺序：
1. jdk标准包
2. java扩展包（例如servlet，javamail，jce等）
3. 使用的外部库的包（例如xml parser）
4. 使用的项目的公共包
5. 使用的模块的其他包
每一类import后面加一个换行。
例如：
import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.mail.*;
import org.apache.xml.*;
import net.ebseries.*;
import net.ebseries.util.*;
import net.ebseries.ebwebmail.*;
u 代码块书写格式
可以选择以下任意一种代码块的书写方式：
if (true){
//body
}
if (true)
{
//body
}
建议使用第二种书写方式。如果是修改他人的代码，必须使用代码原来的书写方式。
对于代码块过长，超过1屏以上，}后面要说明属于那个代码块，例如：
if (i > 100)
{
//too many lines more than one screen
}// if (i > 100)
u 关于缩进
缩进使用4个连续空格，不要在源文件中保存tab字符， 请注意调整所用的IDE工具，打开将tab转换为空格功能。
u 页宽
页宽应该设置为80字符. 源代码一般不会超过这个宽度, 并导致无法完整显示, 但这一设置也可以灵活调整. 在任何情况下, 超长的语句应该在一个逗号或者一个操作符后折行. 一条语句折行后, 应该比原来的语句再缩进4个空格。
u 操作符
操作符左右各用一个空格分隔。
例如：
int a = b;
if (a > 0);
u SQL语句
代码中书写的sql语句要求sql关键字全部大写，表名和字段名小写。例如：
SELECT user_id, name FROM account WHERE user_id > ? AND depart = ? ORDER BY name
u 类和方法定义
类定义或方法定义过长需要换行书写，例如：
public class CounterSet
extends Observable
implements Cloneable
private PortletSet getPortlets( Portlets portlets,
RunData rundata,
boolean application,
boolean applicationsOnly )
{
}
6.1.3 注释
public 和 protected的成员变量和方法必须写javadoc注释。超过1句以上的注释使用中文书写。对于代码多于10行的private方法也要写javadoc注释。
对于代码中的逻辑分支或循环条件需要书写注释，例如：
if (some condition)
{
//符合某个条件，应该这样处理
}
else
{
//否则应该那样处理
}
6.1.4 其他
u 关于属性
类中的属性不能定义为public变量直接存取，而是定义成protect变量并编写get/set方法，例如：
protect String myName;
public String getMyName()
{
return myName;
}
public void setMyName(String myName)
{
this.myName=myName;
}
6.2 jsp/html代码规范
u jsp/html描述注释
jsp/html页面顶部必须存在一个基本描述注释，包含功能描述、参数列表和历史修改信息，例如：
<%--
/**************************************************
*
* NAME : file_download.jsp
*
* PURPOSE : 下载文件提示
*
* PARAMETERS :
* file_id - 文件ID号
* force ?C 是否强制下载
*
* HISTORY
*
* 2002/04/05 Hafele 创建文件
*
* 2002/06/07 tmp 增加强制下在功能
*
*************************************************/
--%>
u jsp头格式
jsp头部一般需要遵循以下格式：
<%@ page contentType="text/html;charset=gb2312" %>
<%@ page import="java.io.*" %> // jdk标准包
<%@ page import="javax.mail.*" %> // java扩展包
<%@ page import="org.apache.xml.*" %> //使用的外部库的包
<%@ page import="com.sunrise..*" %> //使用的项目的公共包
<%@ page import=" com.sunrise.applications.*" %> //使用的模块的其他包
<%@ include file="some.jsp" %> //include其他的jsp
<%
response.setHeader("Pragma","No-cache");
response.setHeader("Cache-Control","no-cache");
response.setHeader("Expires","0");
%> //一般jsp都需要防止缓存
u html格式
1. html头一般需要遵循以下格式：
<head>
<meta http-equiv="Content-Type" content="text/html; charset=gb2312">
<title>some title</title>
<link rel="stylesheet" href="some.css" type="text/css">
<script language="javascript">
//some javascript
</script>
</head>
注意：必须指定一个有意义的<title>，严禁出现“Untitled”或“未命名”之类的<title>。
2. 所有html标签使用小写
3. html页面一般需要设置一个背景色（一般是#FFFFFF）。
u html语法校验
所有的jsp/html页面需要能够使用DreamWeaver正确打开（即html语法正确，没有错误的标记）。
u 注释
一般不使用html注释，除非是有必要让最终用户看到的内容。对于包含JSP代码的html块，必须使用JSP注释。对于没有必要的注释，在发行版本中必须移除。
u form属于域的maxlength
对于text类型的输入域，必须根据数据库字段的长度设置相应的maxlength，例如数据库类型是VARCHAR(64)，那么maxlength是32（因为中文浏览器对于中文也认为是一个字符）。
6.3 其他规范
u 对于IDE的使用
目前暂不限制开发工具的使用，但是最后提交的代码必须不依赖任何IDE，而需要可以使用ant完成所有的编译工作。一般提交的代码目录格式如下：
\
|_dist（存放输出的文件class文件）
|_lib（使用的库）
|_src（源代码）
|_docs（文档）
|_wwwroot（页面文件）
|_build.xml（ant的build文件）
|_changes.log（代码版本和修改的日志）
u 限制session的使用
在代码中使用session需要听取项目经理的意见，项目经理需要在设计文档中登记项目中所有使用到的session的名字和作用。
u 限制外部包的使用
开发员如果需要使用一个外部包需要听取项目经理的意见。在项目经理批准以前，严禁擅自使用一个外部的包。
