软件开发规范.docx

对于需要关闭的标记，必须同其关闭标记同时出现。

不得出现交叉包含的语句。

如下面的代码就是错误的：

2.3.1.7规则–标签的ID

给标签指定ID可以方便的定位相应的页面元素，但是对于在表单（form）中的元素，不要指定ID，而是用name属性，通过form对象实现引用。

这样好处是，当一个页面中有多个form时，form中的元素又有雷同时，防止出现ID相同的元素。

如：

2.3.1.8规则–关于样式

由于项目是一个整体，所以要避免在单个HTML页面中声明样式。

所有的样式统一调用共用的样式文件。

这样有利于修改和维护。

尽量避免在标签上显式的使用样式（style属性），而是通过CSS文件中对相关标签进行样式定义。

对于相同标签不同样式的需求，使用class属性来引用进一步定义的样式。

2.3.1.9规则–HTML不是XHTML

HTML规范和XHTML规范并不相同，在开发中，要注意：

1.不要封闭标签，如用
代替
。

2.对于某些属性，如readonly，enabled，disabled等，并不需要赋值，如：

正确的是

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;

}

if（condition）{

statements;

}else{

statements;

}

if（condition）{

statements;

}elseif（condition）{

statements;

}else{

statements;

}

对于单行语句，也可以简化为：

if（condition）

statement;

if（condition）

statement;

else

statement;

for语句

for语句应该使用如下格式:

代码示例：

for（initialization;condition;update）{

statements;

}

for（variableinobject）{

statements;

}

第一种格式应该和数组使用。

第二种格式应该和对象使用。

注意添加到对象的prototype中的成员将被包含在遍历中。

通过使用hasOwnProperty方法来区分对象的成员是明智的:

代码示例：

for（variableinobject）{

if（object.hasOwnProperty（variable））{

statements;

}

}

对于单行执行的for语句，同样可以简化为

for（initialization;condition;update）

statement;

while语句

while语句应该使用如下格式:

代码示例：

while（condition）{

statements;

}

While语句也可以简化为：

while（condition）

statement;

switch语句

switch语句应该有如下格式:

代码示例：

switch（expression）{

caseexpression:

statements;

break;

default:

statements;

break;

}

每个case和switch对齐，这避免了缩进过度。

每个case以及default代码块最后必须要有break语句，以避免流程进入设计思路的部分。

try语句

try语句应该使用如下格式:

代码示例：

try{

statements;

}catch（variable）{

statements;

}

try{

statements;

}catch（variable）{

statements;

}finally{

statements;

}

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;

color:

#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一起引入页面。

示范：

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