VBScript 程式撰写规格

作者：不详来源：日期：2002-8-7

什麽是程式撰写规格？
程式撰写规格就是一些对您使用 Microsoft Visual Basic Scripting Edition
开发程式时会有帮助的建议。
它包含了下列数项：物件、变数和程序的命名规格

写注解时的规格
文字格式和缩排的使用原则
使用一致的程式撰写规格之主要理由在於可以标准化一个 script 或一组 script 的架构和
程式码样式。如此一来，您和其它人便可以轻松地了解这些程式码的意义。使用良好的程式
撰写规格，可提高原始程式码的精确度、可读性和清晰度，而且可使它与其他程式语言规格
更具一致性和直觉性。

常数命名规格
早期的 VBScript 版本不能建立使用者自订常数。如果需要使用常数时，通常都是以一变数
来当作常数，同时使用全部大写的字母来命名以和一般的变数区别。而每个字之间则使用底
线( _ )字元来做区隔。比如像：
USER_LIST_MAX
NEW_LINE

虽然现在这仍是一个辨别常数的可行办法，但因为现在可以使用 Const 陈述式来建立一个
真正的常数，所以您可能会希望改用另一种命名的架构。这个方式混合了大小写字母，同时
在常数之前加了一个「con」当作字首。比如像：
conYourOwnConstant

变数命名规格
为了维持程式的可读性和一致性，请您在您的 VBScript 程式码内的变数名称前，加上下述
的字首。
[code]

<TABLE WIDTH=60% BORDER=1 CELLPADDING=5 CELLSPACING=0>
<TR BGCOLOR=#DDDDDD VALIGN=TOP>
<TD>子型态</TD>
<TD>字首</TD>
<TD>范例</TD></TR>

<TR VALIGN=TOP>
<TD>Boolean</TD>
<TD>bln</TD>
<TD>blnFound</TD></TR>

<TR VALIGN=TOP>
<TD>Byte</TD>
<TD>byt</TD>
<TD>bytRasterData</TD></TR>

<TR VALIGN=TOP>
<TD>Date (Time)</TD>
<TD>dtm</TD>
<TD>dtmStart</TD></TR>

<TR VALIGN=TOP>
<TD>Double</TD>
<TD>dbl</TD>
<TD>dblTolerance</TD></TR>

<TR VALIGN=TOP>
<TD>Error</TD>
<TD>err</TD>
<TD>errOrderNum</TD></TR>

<TR VALIGN=TOP>
<TD>Integer</TD>
<TD>int</TD>
<TD>intQuantity</TD></TR>

<TR VALIGN=TOP>
<TD>Long</TD>
<TD>lng</TD>
<TD>lngDistance</TD></TR>

<TR VALIGN=TOP>
<TD>Object</TD>
<TD>obj</TD>
<TD>objCurrent</TD></TR>

<TR VALIGN=TOP>
<TD>Single</TD>
<TD>sng</TD>
<TD>sngAverage</TD></TR>

<TR VALIGN=TOP>
<TD>String</TD>
<TD>str</TD>
<TD>strFirstName</TD></TR>

</TABLE>
<H5>变数的有效范围</H5>
变数应该尽可能的定义在最小的有效范围之中。VBScript 变数有下列几种有效范围：

<TABLE WIDTH=70% BORDER=1 CELLPADDING=5 CELLSPACING=0>
<TR BGCOLOR=#DDDDDD VALIGN=TOP>
<TD>有效范围</TD>
<TD>变数宣告的地点</TD>
<TD>可视性</TD></TR>

<TR VALIGN=TOP>
<TD>程序层级</TD>
<TD>事件，函数，或 Sub 程序</TD>
<TD>可见范围在其宣告的程序中</TD></TR>

<TR VALIGN=TOP>
<TD>Script 层级</TD>
<TD>HTML 网页的 HEAD 区段，需写在所有程序之外</TD>
<TD>Script 中的每一个程序都可见</TD></TR>
</TABLE>
<H5>变数有效范围字首</H5>

当 script 很大时，加上变数有效范围字首将可以快速区别变数的有效范围。 
一个置於型态字首之前的单一字母之有效范围字首可以帮我们做到这点， 
同时又不会过度的增加变数名称的长度。

<TABLE WIDTH=70% BORDER=1 CELLPADDING=5 CELLSPACING=0>
<TR BGCOLOR=#DDDDDD VALIGN=TOP>
<TD>有效范围</TD>
<TD>字首</TD>
<TD>范例</TD></TR>

<TR VALIGN=TOP>
<TD>程序层级</TD>
<TD>不必加</TD>
<TD>dblVelocity</TD></TR>

<TR VALIGN=TOP>
<TD>Script 层级</TD>
<TD>s</TD>
<TD>sblnCalcInProgress</TD></TR>

</TABLE>

</BLOCKQUOTE>

<H5>有说明性的变数和程序名称</H5>

变数和程序名称应该使用大小写混合的命名名称， 
同时这个名称应该尽可能地能够说明变数的用途。 
此外，程序名称应该以动词开头，比如像 InitNameArray 或 CloseDialog。

对於一些经常使用的长名词，我们建议您使用标准的缩写，以免名称过长。 
一般来说，名称长度如果超过32 个字元就很难阅读。当您使用缩写时， 
请在全部的script 中都保持相同的缩写方式。举例来说， 
如果您在一个 script 或一组 script 中时而用 Cnt，时而用Count， 
那麽有时可能会造成困扰。 

<H5>物件命名规格 </H5>
下清单格列出了您在撰写 VBScript 时会遭遇的物件型态及建议的命名规格。

<TABLE WIDTH=70% BORDER=1 CELLPADDING=5 CELLSPACING=0>
<TR BGCOLOR=#DDDDDD VALIGN=TOP>
<TD>物件型态</TD>
<TD>字首</TD>
<TD>范例</TD></TR>

<TR VALIGN=TOP>
<TD>3D Panel</TD>
<TD>pnl</TD>
<TD>pnlGroup</TD></TR>

<TR VALIGN=TOP>
<TD>Animated button</TD>
<TD>ani</TD>
<TD>aniMailBox</TD></TR>

<TR VALIGN=TOP>
<TD>Check box</TD>
<TD>chk</TD>
<TD>chkReadOnly</TD></TR>

<TR VALIGN=TOP>
<TD>Combo box, drop-down list box</TD>
<TD>cbo</TD>
<TD>cboEnglish</TD></TR>

<TR VALIGN=TOP>
<TD>Command button</TD>
<TD>cmd</TD>
<TD>cmdExit</TD></TR>

<TR VALIGN=TOP>
<TD>Common dialog</TD>
<TD>dlg</TD>
<TD>dlgFileOpen</TD></TR>

<TR VALIGN=TOP>
<TD>Frame</TD>
<TD>fra</TD>
<TD>fraLanguage</TD></TR>

<TR VALIGN=TOP>
<TD>Horizontal scroll bar</TD>
<TD>hsb</TD>
<TD>hsbVolume</TD></TR>

<TR VALIGN=TOP>
<TD>Image</TD>
<TD>img</TD>
<TD>imgIcon</TD></TR>

<TR VALIGN=TOP>
<TD>Label</TD>
<TD>lbl</TD>
<TD>lblHelpMessage</TD></TR>

<TR VALIGN=TOP>
<TD>Line</TD>
<TD>lin</TD>
<TD>linVertical</TD></TR>

<TR VALIGN=TOP>
<TD>List Box</TD>
<TD>lst</TD>
<TD>lstPolicyCodes</TD></TR>

<TR VALIGN=TOP>
<TD>Spin</TD>
<TD>spn</TD>
<TD>spnPages</TD></TR>

<TR VALIGN=TOP>
<TD>Text box</TD>
<TD>txt</TD>
<TD>txtLastName</TD></TR>

<TR VALIGN=TOP>
<TD>Vertical scroll bar</TD>
<TD>vsb</TD>
<TD>vsbRate</TD></TR>

<TR VALIGN=TOP>
<TD>Slider</TD>
<TD>sld</TD>
<TD>sldScale</TD></TR>
</TABLE>

<H5>程式注解规格</H5>
所有的程序都应该以一简短的注解当作开头来解释程序的功用。这些说明不必解释程式制作 
的细节 (它怎麽做到的)，因为这些内容可能时时会改变。如此一来，您就不必做一些不必 
要的注解维护工作，或是让您的注解错误百出。这些程式码本身和所有必要的行间注解就足 
以说明制作的方式。 

当要传递到程序中的引数之目的不是很明显时，或是程序预期引数的值应该介於某个范围之 
间时，您就应该在注解中说明。函数的传回值以及会被程序更动的变数，特别是经由引用的 
引数，也都应该写在程序的前头的注解中。

程序的开头注解应该包含下列几个区段标题。您可以叁考以下「格式化您的程式码」中的例 子。

<TABLE WIDTH=70% BORDER=1 CELLPADDING=5 CELLSPACING=0>
<TR BGCOLOR=#DDDDDD VALIGN=TOP>
<TD WIDTH=15%>区段标题</TD>
<TD>注解内容</TD>

<TR VALIGN=TOP>
<TD WIDTH=15%>目的(Purpose)</TD>
<TD>程序的功用(不是如何达成其功用)。</TD>

<TR VALIGN=TOP>
<TD WIDTH=15%>假设(Assumptions)</TD>
<TD>列出任何会影响这个程序的外部变数、控制项或其它元件。</TD>

<TR VALIGN=TOP>
<TD WIDTH=15%>影响(Effects)</TD>
<TD>列出这个程序会影响的任何外部变数、控制项或其它元件。</TD>

<TR VALIGN=TOP>
<TD WIDTH=15%>输入(Inputs)</TD>
<TD>解释每一个没有明显功能的引数。每一个引数都应该自成一行，同时使用行间注解。</TD>

<TR VALIGN=TOP>
<TD WIDTH=15%>传回值(Return Values)</TD>
<TD>解释传回值的意义。</TD>
</TABLE>

请记得下列几个要点：
<UL>
<LI>每一个重要变数的宣告都应该伴随着一个行间注解来说明变数的功用。 
<LI>变数、控制项和程序的名称都应该要令人可以一目了然。行间注解只需要用在一些较复 
杂的程式细节部分。
<LI>在 script 的开头，您应该包含一段描述整个 script 的概观，同时列举物件、程序、 
演算法、对话方块以及其它和系统相关的事项。有时用一段虚拟码来说明演算法可能会有不 
小的帮助。
</UL>

<H5>格式化您的程式码</H5>
<BLOCKQUOTE>
尽可能保留萤幕的空间，但是同时要让您的程式格式可以反映程式的逻辑结构和巢状架构。 
这里有几个要点：
<UL>
<LI>标准的巢状区块应该用四个空格缩排。 
<LI>一个程序的概观注解应该用一个空格缩排。
 <LI>紧接在概观注解後的最高层级陈述式应该要用四个空格缩排，其中的巢状区块则再 用四
个空格缩排。
下面是一个例子：
</UL>
[/code]
'*********************************************************
' Purpose: Locates the first occurrence of a specified user
' in the UserList array.
' Inputs: strUserList(): the list of users to be searched.
' strTargetUser: the name of the user to search for.
' Returns: The index of the first occurrence of the strTargetUser
' in the strUserList array.
' If the target user is not found, return -1.
'*********************************************************

Function intFindUser (strUserList(), strTargetUser)
 Dim i ' Loop counter.
 Dim blnFound ' Target found flag
 intFindUser = -1
 i = 0 ' Initialize loop counter
 Do While i <= Ubound(strUserList) and Not blnFound
 If strUserList(i) = strTargetUser Then
 blnFound = True ' Set flag to True
 intFindUser = i ' Set return value to loop count
 End If
 i = i + 1 ' Increment loop counter
 Loop
End Function