软件开发规范Word格式.docx
《软件开发规范Word格式.docx》由会员分享，可在线阅读，更多相关《软件开发规范Word格式.docx（45页珍藏版）》请在冰豆网上搜索。
2.2.1文件命名规范
2.2.1.1规则–所有文件名均由小写字母、数字和下划线组成
使用的英文单词要简单，同时又能清晰的反映该文件功能。
下划线只做为单词的分隔符，不要用下划线做文件名的起始。
文件名中不得包含汉字、空格和特殊字符。
示例:
driver_task.html
2.2.1.2规则–所有HTML文件的扩展名为.html
文件扩展名为小写的html，避免使用htm或者大写字母。
login.html
2.2.1.3规则–所有JavaScript文件的扩展名为.js
文件扩展名为小写字母的js
comon.js
2.2.1.4规则–所有CSS文件的扩展名为.css
文件扩展名为小写字母的css
style.css
2.2.1.5规则–所有页面源代码使用UTF-8编码
所有HTML文件、JavaScript文件、CSS文件使用UTF-8编码。
2.2.2目录结构规范
2.2.2.1规则–符合标准的JavaWeb目录规范
系统应该符合JavaWeb目录规范：
[web根目录]
|__script//公用JavaScript目录
|__css//公用css目录
|__images//公用图片目录
|__swf//公用flash目录
|__xxxx//html文件目录，根据业务关联程度分目录
|__yyyy
|__…
|__WEB-INF//标准Web配置文件目录
|__classes//Java二进制代码目录
|__lib//Javalib库目录
|__web.xml//标准Web配置文件
2.2.2.2规则–公用的JavaScript文件放入script目录，公用的CSS文件放入css目录
在各个html页面中直接引用这些公用的文件
<
scripttype="
text/JavaScript"
src="
/script/common.js"
language="
JavaScript"
>
/script>
2.2.2.3规则–公用的图片文件放入images目录
系统公用的图片文件放入web根目录下的images目录，为了便于管理，应按照使用功能建立子目录。
2.2.2.4规则–公用的flash文件放入swf目录
系统公用的flash文件放入web根目录下的swf目录，为了便于管理，应按照使用功能建立子目录。
2.2.2.5规则–HTML文件根据业务关联程度分别放入各一级目录
一级目录是指和上面提到的script、css并列的目录。
如清算部分充值报表的页面就在目录clear下：
/clear/deposit_stat.html；
根目录下只存放index页面及其所包含的帧页面，其他公用的html页面放在目录common目录下。
2.2.2.6建议–保持两层目录结构
整个web应用保持由根目录和一级目录组成的两层目录结构。
2.3标记语言规范
标记语言是指用来结构化呈现内容的标记语言，如HTML，XHTML或WML等。
本项目覆盖范围为HTML（普通浏览器访问）和XHTML（手机访问）。
2.3.1HTML开发规范
项目中所有的HTML页面遵循W3C组织推荐的HTML4.01规范。
（手机门户页面规范除外，见相关规范）
其中，普通页面遵循TransitionalDTD，帧（frame）页面遵循FramesetDTD。
2.3.1.1规则–正确声明文档的DTD
在各个HTML文件的首行必须声明本文件的DTD
普通页面的声明是：
!
DOCTYPEHTMLPUBLIC"
-//W3C//DTDHTML4.01Transitional//EN"
"
http:
//www.w3.org/TR/html4/loose.dtd"
>
帧页面的声明是：
-//W3C//DTDHTML4.01Frameset//EN"
//www.w3.org/TR/html4/frameset.dtd"
2.3.1.2规则–正确填写文档类型
正确填写meta中的文档类型
示例：
metahttp-equiv="
Content-Type"
content="
text/html;
charset=utf-8"
2.3.1.3规则–填写文档作者
在meta填写作者信息
metaname="
author"
guoang"
2.3.1.4规则–填写title
虽然系统采用了frame，导致部分页面设置的title没有显示效果，但是中的title必须设置，以简要说明这个页面的用途
title>
退款明细查询<
/title>
2.3.1.5规则–缩进文档
使用TAB对文档进行缩进，以保证文档良好的可读性。
最高一级的父标记采用左对齐顶格方式书写。
同一级标记的首字符上下必须对齐。
html>
head>
<
metah…………….
…………
2.3.1.6规则–适当换行
每个标签占一行，不得出现两个标记在同一行的情况。
如：
tablecellSpacing="
0"
cellPadding="
4"
width="
100%"
border="
如果标签体为空或者内容很少，则标签体和对应的结束标签可在同一行。
如果标签体和标签不在一行上，则标签体需要缩进。
divclass="
listBar"
listTitle"
退款明细<
/div>
对于需要关闭的标记，必须同其关闭标记同时出现。
不得出现交叉包含的语句。
如下面的代码就是错误的：
div>
p>
abc<
/p>
2.3.1.7规则–标签的ID
给标签指定ID可以方便的定位相应的页面元素，但是对于在表单（form）中的元素，不要指定ID，而是用name属性，通过form对象实现引用。
这样好处是，当一个页面中有多个form时，form中的元素又有雷同时，防止出现ID相同的元素。
formid="
searchForm"
name="
action="
"
<
inputtype="
hidden"
orgID"
2.3.1.8规则–关于样式
由于项目是一个整体，所以要避免在单个HTML页面中声明样式。
所有的样式统一调用共用的样式文件。
这样有利于修改和维护。
尽量避免在标签上显式的使用样式（style属性），而是通过CSS文件中对相关标签进行样式定义。
对于相同标签不同样式的需求，使用class属性来引用进一步定义的样式。
2.3.1.9规则–HTML不是XHTML
HTML规范和XHTML规范并不相同，在开发中，要注意：
1.不要封闭标签，如用<
br/>
代替<
br>
。
2.对于某些属性，如readonly，enabled，disabled等，并不需要赋值，如：
button"
value="
确认"
onclick="
onRefer（）"
enabled="
true"
正确的是
enabled>
2.3.1.10建议–采用对XHTML更友好的方式
为了使页面对XHTML更友好，建议：
1.所有标签和属性均采用小写；
2.使用双引号将所有的属性值括起来。
2.3.2XHTML开发规范（TODO）
2.4JavaScript开发规范
2.4.1规范
项目使用符合ECMA-262v3规范的JavaScript1.5做为页面脚本语言。
2.4.1.1规则–缩进文档
使用TAB对文档进行缩进，以保证文档良好的可读性
functionclone（object）{
varobj=null;
if（objectinstanceofArray）{
……
2.4.1.2规则–行宽
不要让一行代码超过120个字符。
当一条语句不能在单独一行写完时，可能有必要拆分它。
在操作符后进行拆分，最好是在逗号后面拆分。
下一行应该多缩进一个tab。
2.4.1.3规则–注释
注释应该书写良好和清晰，就像它们标注的代码一样。
注意及时更新注释，错误的注释让程序更难读懂和理解。
让注释有意义。
更多的关注于不能马上可见的东西。
不要用如下内容浪费读者的时间：
i=0;
//给变量i赋0
一般使用行注释。
把块注释用于正式文档或外部注释。
2.4.1.4规则–变量声明
所有的变量应该在使用前声明。
JavaScript不强求这点，但是这样做会让程序更易读，并且会让探测未声明的可能变成隐式的globals的变量更容易。
var语句应该在方法体内开始部分。
每个变量声明应该自己占一行并有注释。
代码示例：
varcurrentOrg;
//当前机构
varorgLevel;
//机构等级
varoperator;
//当前操作员
例外：
同类变量可在一行声明，如：
vari,j,k;
在方法顶端定义所有变量。
尽量少使用全局变量。
不使用隐式的全局变量。
2.4.1.5规则–方法声明
所所有的方法应该在它们使用前声明。
内部方法应该位于var语句后面。
这让那些变量包含在它的scope里更清楚。
方法体本身缩进1个tab。
“}”（右大括号）应该和方法声明处对齐。
function$（element）{
if（typeofelement=='
string'
）
returndocument.getElementById（element）;
else
returnelement;
}
这个规范可以和JavaScript很好的工作，因为在JavaScript里方法和对象字面量可以放在允许表达式的任何位置。
它使用内部方法和复杂结构提供最好的可读性。
functionlock（）{
varids=Common.getCheckBoxValue（"
checkboxs"
）;
if（!
ids）
showError（"
请选择需要冻结的操作员。
else{
if（showQuestion（"
是否冻结这些操作员？
））
DWR.call（"
partyService.lockOperators"
ids,function（）{
showInformation（"
冻结操作员成功"
showData（）;
}）;
}
}
2.4.1.6规则–命名
命名应该由26个大小写字母（A..Z,a..z），10个数字（0..9）和_（下划线）组成。
不要使用国际字符，因为它们可能不易读或者不能在任何地方都能容易理解。
不要在名字里使用$（美元符号）或\（反斜线符号）。
不要使用_（下划线）作为名字的首字母。
它有时被用来表示私有，但是在JavaScript中它实际上不提供私有性。
如果私有性很重要，使用提供私有性的私有成员。
大多数变量和方法名应该以小写字母开始。
必须使用new前缀的构造函数应该以大写字母开始。
JavaScript不会在省略new时报编译期警告或运行时警告。
不使用new时会系统可能会出现难以判断原因的异常情况，大写首字母规范是有效的预防措施。
公用函数库中有名为$的函数，用于方便的根据元素的id来获取这个object
2.4.1.7规则–语句
简单语句
每行应该包含至少一个语句。
在每个简单语句末尾添加一个“;
”（分号）。
JavaScript允许任何表达式作为语句使用。
这可能产生一些错误，特别是在插入分号时。
唯一可以当作语句使用的表达式是赋值表达式和调用表达式。
复合语句
复合语句是包含一个用“{}”（大括号）包围语句列表的的语句。
1，包围的语句应该再缩进1个tab。
2，“{”（左大括号）应该位于开始复合语句的行的末尾。
3，“}”（右大括号）应该新起一行并且和相匹配的“{”所在那行的起始位置对齐
4，当语句是控制结构的一部分时，所有语句都应该用括号包围，即使是单行语句，例如if或for语句。
这让添加语句更容易而且不会引起BUG。
标签
语句标签是可选的。
只有如下语句需要被标签标识:
while，do，for，switch。
return语句
具有值的return语句不应该使用“（）”（圆括号）包围值。
返回值表达式必须和return关键字在同一行从而避免插入分号。
if语句
if语句应该使用如下格式:
if（condition）{
statements;
}
}else{
}elseif（condition）{
对于单行语句，也可以简化为：
if（condition）
statement;
statement;
else
for语句
for语句应该使用如下格式:
for（initialization;
condition;
update）{
for（variableinobject）{
第一种格式应该和数组使用。
第二种格式应该和对象使用。
注意添加到对象的prototype中的成员将被包含在遍历中。
通过使用hasOwnProperty方法来区分对象的成员是明智的:
if（object.hasOwnProperty（variable））{
}
对于单行执行的for语句，同样可以简化为
update）
while语句
while语句应该使用如下格式:
while（condition）{
While语句也可以简化为：
while（condition）
switch语句
switch语句应该有如下格式:
switch（expression）{
caseexpression:
statements;
break;
default:
statements;
break;
每个case和switch对齐，这避免了缩进过度。
每个case以及default代码块最后必须要有break语句，以避免流程进入设计思路的部分。
try语句
try语句应该使用如下格式:
try{
}catch（variable）{
}finally{
2.4.1.8规则–空格
空行通过将逻辑相关的代码放到一起来增加可读性。
空格应该用于如下情况:
1，关键字后面跟“（”（左圆括号）时应该用一个空格隔开。
2，方法名和方法的“（”（左圆括号）之间不要有空格。
这利于区分关键字和方法调用。
3，所有的二元操作符，除了“.”（圆点）、“（”（左圆括号）和“[”（左中括号），都应该使用一个空格来和操作数隔开。
4，一元操作符和操作数之间不应该使用空格隔开，除了操作符是一个单词时，如typeof。
5，for语句控制部分的每个“;
”（分号）应该在后面跟一个空格。
6，每个“,”（逗号）后面应该跟一个空格。
2.4.1.9建议–其他建议
{}和[]
使用{}替代newObject（）。
使用[]替代newArray（）。
当成员名字为连续的整数时使用数组。
当成员名字为任意的字符串或名字时使用对象。
赋值表达式
不要在if和while语句的条件部分做赋值。
不要写不易懂的代码。
2.5CSS文件
2.5.1规范
项目使用符合W3C所定义的CascadingStyleSheets,level2（CSS2）规范的样式单语言。
原则上，项目中的CSS文件由专人统一开发、维护。
2.5.1.1规则–缩进文档
使用TAB对文档进行缩进，个属性/值之间换行分隔，以保证文档良好的可读性
.listBar{
color:
#000;
font-weight:
bold;
height:
26px;
2.5.1.2规则–命名
样式名使用英文（包括简写）单词和字母组成，样式名的第一个字符必须为小写字母，使用多个单词组成的样式名单词首字母大写。
.searchForm{
border-bottom:
1pxsolid#8DB0DB;
background-color:
#F9FFF4;
padding-top:
4px;
margin:
0px;
}……
重新定义的标签名，标签名全部使用大写字母。
TABLE{
font:
12pxSimSun,Tahoma,Verdana;
#333333;
empty-cells:
show;
2.5.1.3规则–注释
按照样式的分类为样式单文件添加注释，方便样式的扩展和修改。
/***按钮***/
.treeBtn……
2.6页面设计
2.6.1页面设计原则
Ø
使用广泛支持的技术。
兼容流行的浏览器及版本（如Firefox3，IE8.0等）为标准，同时照顾其他软件或低版本。
CSS样式和JavaScript代码注意复用，尽量提取公用部分以引用的方式供HTML文件使用。
不使用过小的字体不使用过大的图片，不使用过长的滚屏。
图片采用gif,jpg压缩格式，以减小页面下载数据量。
2.6.2页面常用模式
这部分内容需要随着需求设计的进行及时进行修订
2.6.2.1使用统一的JavaScript库
系统所有公用的JavaScript库保存在script目录下。
建议所有页面都引用common.js，该script会把公用的JavaScript一起引入页面。
示范：
scriptLANGUAGE="
type="
2.6.2.2使用统一的CSS文件控制页面样式，便于系统换肤
在公用JavaScript库theme.js中，会根据用户保存在Cookie中的样式变量，选择不同的css文件，控制页面样式。
系统的缺省样式文件是css/style.css文件，其它的样式文件也应该放在这个目录下。
页面只需要引用common.js文件，theme.js文件会通过common.js被自动加载，无需其它代码。
2.6.2.3页面主框架（TODO）
页面主框架分为三个frame
顶部框架，此框架主要用于显示系统主要功能菜单和登录用户信息，页面元素包括：
logo，主菜单，当前用户信息，注销按钮等。
左侧框架，此框架主要用于显示业务功能菜单，界面元素包括：
树状导航菜单。
右侧主框架，此框架主要用于显示各功能模块的操作页面。
主显示框架如下图所示：
（下图的样式只供参考）
图表1主显示框架
2.6.2.4页面流转模式
在本系统中，使用JavaScript代码实现页面的流转，不依赖于任何框架。
页面流转共有以下几种类型：
1.页面内部不同DIV的切换。
这种方式的好处是速度快，缺点是不支持浏览器的回退。
适合用于关联性很强的两个页面之间，例如列表和明细。
Funlib.js中封装了setPages和switchPage方法来实现DIV切换。
示范代码：
//页面初始化
functionload（）{
showNav（）;
setPages（["
pwdDetail"
"
detailForm"
l
升级会员 