通过实例编写开发规范文档
第三章 网站开发
第一节 网站开发基础
一、环境搭建
1、Microsoft Visual Basic 2005
2、Microsoft SQL Server 2005
3、Adobe Dreamweaver CS5
4、Adobe Photoshop CS5
5、Microsoft Office Visio 2003
二、规范开发
在这一节我们将学习编写开发规范文档。为什么要编写开发规范文档？因为我们的系统开发往往需要一个团队开发，为了使团队中的每一位成员都形成统一的开发约定。通过规范文档可以给各程序员之间起到沟通的桥梁的作用，并增强程序的可读性。下面我们还是通过“中国滑雪网”实例学写规范文档。
开发规范文档跟需求文档结构相似：1、封皮 “中国滑雪网”开发规范文档；2、目录；3、正文。下面是具体的内容。
目录
目录... 1
1． 编写目的.......................................................................................................................................................... 2
2． 程序命名规范.................................................................................................................................................... 2
基本约定....................................................................................................................................................................... 2
控件命名规范................................................................................................................................................................. 4
ADO.NET控件命名规范.................................................................................................................................................... 5
自定义控件命名规范......................................................................................................................................................... 6
类型声明...................................................................................................................................................................... 6
常量............................................................................................................................................................................ 7
类的命名...................................................................................................................................................................... 7
抽象类定义................................................................................................................................................................... 7
密封类定义.................................................................................................................................................................. 8
方法定义..................................................................................................................................................................... 8
虚方法定义.................................................................................................................................................................. 8
类的成员定义............................................................................................................................................................... 8
结构定义..................................................................................................................................................................... 8
结构成员定义............................................................................................................................................................... 8
接口定义..................................................................................................................................................................... 9
接口的方法和成员定义.................................................................................................................................................... 9
自定义异常定义............................................................................................................................................................ 9
注释规范.................................................................................................................................................................... 9
1、编写目的
为了使团队中的每一位成员都形成统一的开发约定，特制定本规范文档，在今后的开发过程中，请严格按照此文档约定的规则进行编码。通过此规范，希望可以给各程序员之间起到沟通的桥梁的作用，并增强程序的可读性。
如在使用过程中，碰到本文档中没进行约定的规则，待商议后对该文档进行补充完善。
2、程序命名规范
基本约定
l 所有的命名名称都必须使用能直接体现具体含义的名字。
不能使用X，Y，Z，等无意义的名称进行定义，除循环变量除外。
l 所有的成员变量必须在所有成员方法前面声明，用一个换行把它和方法分开
如:
public class ClsLogin
{
TextBox txtUserName;//
TextBox txtPassWord;//
public Login()
{
}
}
l 类文件名的名称必须要能反应类的内容，最好是和类同名，一个文件只写一个类，文件和文件夹的名称也应该精确地说明它们的用途。
如：
文件名：Login.cs
类名：public class ClsLogin
l 大括号"{"要新起一行。
正确编写：
public class ClsLogin
{
}
错误编写：
public class ClsLogin{
}
l switch语句一定要有default来处理意外情况。
l 同程序外部连接（如连接数据库、接口、文件等）一定要捕获任何类型的异常（try）给出友好的消息给用户，必要时用日志记录错误的细节，包括发生的时间，和相关方法，类名等。
l 始终使用"{ }"包含if/else下的语句，即使只有一条语句。
正确编写：
if (true)
{
//语句。
}
错误编写：
if (true)
//语句。
l 把引用的系统的namespace和自定义或第三方的分开。
using System;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using MYNameSpace.NameSpace;
l 不同函数或方法之间，需要用空行来分开。
如：
public class ClsLogin
{
public Login()
{
}
Public ~Login()
{
}
}
l 不在代码中使用具体的路径和驱动器名，必须使用相对路径。
l 代码的缩进用Tab，而不要用space。
l 使用某个控件的值时，尽量命名局部变量。
public string GetTitle()
{
string StrTitle=lblTitle.Text;
StrTitle += StrTitle;
return StrTitle;
}
l 一个方法只完成一个任务。不要把多个任务组合到一个方法中。
l 避免使用大文件。如果一个文件里的代码超过300～400行，必须考虑将代码分开到不同类中。
控件命名规范
以下控件为常用的控件命名规范，按英文字母进行升序排列。在此列表中未定义的控件，将后期补充完善。
|
控件类型 |
命名前缀 |
举例 |
|
Panel |
pnl |
pnlTtitle |
|
Button |
btn |
btnLogin |
|
Check box |
chk |
chkOk |
|
Combo box |
cbo |
cboInfoSort |
|
Dropdown list box |
ddl |
ddlCity |
|
Data |
dat |
datUser |
|
Control |
ctr |
ctrInfo |
|
Data grid |
dgd |
dgdUserList |
|
Data list |
dbl |
dblInfo |
|
Data repeater |
drp |
drpInfo |
|
Directory list box |
dir |
dirSource |
|
Image |
img |
imgIcon |
|
Label |
lbl |
lblHelpMessage |
|
Text box |
txb |
txbName |
|
List box |
lst |
lstInfo |
|
TreeView |
tre |
treOrganization |
ADO.NET控件命名规范
|
类型 |
前缀 |
示例 |
|
Connection |
con |
conNorthwind |
|
Command |
cmd |
cmdReturnProducts |
|
Parameter |
parm |
parmProductID |
|
DataAdapter |
dad |
dadProducts |
|
DataReader |
dtr |
dtrProducts |
|
DataSet |
dst |
dstNorthWind |
|
DataTable |
dtbl |
dtblProduct |
|
DataRow |
drow |
drowRow98 |
|
DataColumn |
dcol |
dcolProductID |
|
DataRelation |
drel |
drelMasterDetail |
|
DataView |
dvw |
dvwFilteredProducts |
自定义控件命名规范
自定义控件注册时，必须以“Custom“申明。
例如：
<%@ Register TagPrefix="Custom" Namespace="CustomComponents" %>
使用时：
<Custom:CreditCardForm runat="server" ID="customCreditCard” />
类型声明
在定义变量时，以前缀开头，再加上变量声明符，为了不与系统控件命名起冲突，类型命名时，前缀第一个字母大写。
l 整型
|
类型 |
前缀 |
示例 |
|
Sbyte |
Sby |
SbySex |
|
Short |
Shr |
ShrAverage |
|
Int |
Int |
IntRowCounter |
|
Long |
Lng |
LngBillGatesIncome |
|
Byte |
Byt |
BytPixelValue |
|
Ushort |
Ushr |
UshrMoney |
|
Uint |
Uint |
UintCount |
|
Ulong |
Ulng |
UlngCount |
l 浮点型
|
类型 |
前缀 |
示例 |
|
Flost |
Fot |
FotMoney |
|
Double |
Dou |
DouMoney |
|
Decimal |
Dec |
DecMoney |
l Bool类型
|
类型 |
前缀 |
示例 |
|
Bool |
Boo |
BooIsPostBack |
l 字符类型
|
类型 |
前缀 |
示例 |
|
Char |
Chr |
ChrSelectSex |
l 引用类型
|
类型 |
前缀 |
示例 |
|
Object |
Obj |
ObjReturnValue |
|
String |
Str |
StrName |
常量
全部大写，单词之间以 “_” 分隔，例：USER_PASSWORD。
类的命名
类名必须以Cls前缀开头。
例如:
public class ClsTextBox
{
public void DataBind()
{
}
}
抽象类定义
抽象类必须以AbsCls前缀开头。
例如：
public abstract class AbsClsTextBox
{
}
密封类定义
密封类必须以SeaCls前缀开头。
例如：
public sealed class SeaClsTextBox
{
}
方法定义
大小写形式，一般将其命名为动宾短语.
如：
ShowDialog()
CreateFile()
虚方法定义
在方法定义的基础上，加上Vir前缀来表示虚方法。
如：
public virtual string VirShowDialog ()
{
}
public virtual string VirCreateFile ()
{
}
类的成员定义
参照类型声明；
结构定义
结构名必须以Srt前缀开头。
如:
public struct SrtDimensions
{
public string StrName;
public string StrPassword;
}
结构成员定义
参照类型声明；
接口定义
接口名称前加I前缀开头。
interface ICompare
{
}
接口的方法和成员定义
参照类的方法和成员的定义规则。
自定义异常定义
自定义异常类型以Cls前缀开头，以Exception作为后缀命名。
例：
public class ClsMyException : Exception
{
}
注释规范
1、 注释必须使用中文及中文的标点符号。
2、 每行注释的最大长度不能超过1024*800的宽度，且需要与代码对齐。
3、 将注释与注释分隔符用一个空格分开。
4、 编码的同时书写注释。
5、 重要变量必须有注释。
6、 变量注释和变量在同一行，所有注释必须对齐，与变量分开至少两个Tab键。
7、 典型算法必须有注释。
8、 在循环和逻辑分支的地方必须写上注释。
9、 程序段或语句的注释在程序段或语句的上一行。
10、 在代码交付之前，必须删掉临时的或无关的注释。
文件与函数的注释
1、 文件和函数的头部都必须有概述注释信息。
2、 文件和函数的概述注释应缩进1个空格。
3、 文件概述注释信息必须包括以下内容：
a) 文件名
b) 属性
c) 创建人
d) 创建日期
4、 函数概述注释信息必须包括以下内容：
a) 功能
b) 输入参数，标明意义和类型
c) 返回值，标明意义和类型
d) 作者
e) 创建日期
