VBScript 编码约定

March 25,2004

<h5>什么是编码约定？</h5>

 编码约定是帮助您使用 Microsoft Visual Basic Scripting Edition
 编写代码的一些建议。编码约定包含以下内容： <ul>
<li>对象、变量和过程的命名约定 </li>
<li>注释约定 </li>
<li>文本格式和缩进指南 </li>
 </ul>
 使用一致的编码约定的主要原因是使 Script 或 Script
 集的结构和编码样式标准化，这样代码易于阅读和理解。使用好的编码约定可以使源代码明白、易读、准确，更加直观且与其他语言约定保持一致。
 

<h5>常数命名约定</h5>

 VBScript
 的早期版本不允许创建用户自定义常数。如果要使用常数，则常数以变量的方式实现，且全部字母大写以和其他变量区分。常数名中的多个单词用下划线
 (_) 分隔。例如： 

 USER_LIST_MAX
NEW_LINE


 这种标识常数的方法依旧可行，但您还可以选择其他方案，用 Const
 语句创建真正的常数。这个约定使用大小写混合的格式，并以“con”作为常数名的前缀。例如：
 

 conYourOwnConstant


<h5>变量命名约定</h5>

 出于易读和一致性的目的，请在 VBScript
 代码中使用以下变量命名约定：
 <table WIDTH="87%" 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="87%" 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>在声明变量的过程中可见</td>
</tr>
<tr VALIGN="TOP">
 <td>Script 级</td>
 <td>HTML 页面的 HEAD 部分，任何过程之外</td>
 <td>在 Script 的所有过程中可见</td>
</tr>
 </table>
 <h5>变量作用域前缀</h5>
 随着 Script
 代码长度的增加，有必要快速区分变量的作用域。在类型前缀前面添加一个单字符前缀可以实现这一点，而不致使变量名过长。
 <table WIDTH="87%" 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>

<h5>描述性变量名和过程名</h5>

 变量名或过程名的主体应使用大小写混合格式，并且尽量完整地描述其目的。另外，过程名应以动词开始，例如
 InitNameArray 或 CloseDialog。
 对于经常使用的或较长的名称，推荐使用标准缩写以使名称保持在适当的长度内。通常多于
 32 个字符的变量名会变得难以阅读。使用缩写时，应确保在整个
 Script 中保持一致。例如，在一个 Script 或 Script 集中随意切换 Cnt 和
 Count 将造成混乱。 

<h5>对象命名约定</h5>

 下表列出了 VBScript 中可能用到的对象命名约定（推荐）：
 <table WIDTH="87%" BORDER="1" CELLPADDING="5" CELLSPACING="0">
<tr BGCOLOR="#DDDDDD" VALIGN="TOP">
 <td>对象类型</td>
 <td>前缀</td>
 <td>示例</td>
</tr>
<tr VALIGN="TOP">
 <td>3D 面板</td>
 <td>pnl</td>
 <td>pnlGroup</td>
</tr>
<tr VALIGN="TOP">
 <td>动画按钮</td>
 <td>ani</td>
 <td>aniMailBox</td>
</tr>
<tr VALIGN="TOP">
 <td>复选框</td>
 <td>chk</td>
 <td>chkReadOnly</td>
</tr>
<tr VALIGN="TOP">
 <td>组合框、下拉列表框</td>
 <td>cbo</td>
 <td>cboEnglish</td>
</tr>
<tr VALIGN="TOP">
 <td>命令按钮</td>
 <td>cmd</td>
 <td>cmdExit</td>
</tr>
<tr VALIGN="TOP">
 <td>公共对话框</td>
 <td>dlg</td>
 <td>dlgFileOpen</td>
</tr>
<tr VALIGN="TOP">
 <td>框架</td>
 <td>fra</td>
 <td>fraLanguage</td>
</tr>
<tr VALIGN="TOP">
 <td>水平滚动条</td>
 <td>hsb</td>
 <td>hsbVolume</td>
</tr>
<tr VALIGN="TOP">
 <td>图像</td>
 <td>img</td>
 <td>imgIcon</td>
</tr>
<tr VALIGN="TOP">
 <td>标签</td>
 <td>lbl</td>
 <td>lblHelpMessage</td>
</tr>
<tr VALIGN="TOP">
 <td>直线</td>
 <td>lin</td>
 <td>linVertical</td>
</tr>
<tr VALIGN="TOP">
 <td>列表框</td>
 <td>lst</td>
 <td>lstPolicyCodes</td>
</tr>
<tr VALIGN="TOP">
 <td>旋钮</td>
 <td>spn</td>
 <td>spnPages</td>
</tr>
<tr VALIGN="TOP">
 <td>文本框</td>
 <td>txt</td>
 <td>txtLastName</td>
</tr>
<tr VALIGN="TOP">
 <td>垂直滚动条</td>
 <td>vsb</td>
 <td>vsbRate</td>
</tr>
<tr VALIGN="TOP">
 <td>滑块</td>
 <td>sld</td>
 <td>sldScale</td>
</tr>
 </table>

<h5>代码注释约定</h5>

 所有过程的开始部分都应有描述其功能的简要注释。这些注释并不描述细节信息（如何实现功能），这是因为细节有时要频繁更改。这样就可以避免不必要的注释维护工作以及错误的注释。细节信息由代码本身及必要的内部注释来描述。
 当传递给过程的参数的用途不明显，或过程对参数的取值范围有要求时，应加以说明。如果过程改变了函数和变量的返回值（特别是通过参数引用来改变），也应在过程的开始部分描述该返回值。
 过程开始部分的注释应包含以下区段标题。相关样例，请参阅后面的“格式化代码”部分。
 <table WIDTH="87%" BORDER="1" CELLPADDING="5" CELLSPACING="0">
<tr BGCOLOR="#DDDDDD" VALIGN="TOP">
 <td WIDTH="15%">区段标题</td>
 <td>注释内容</td>
</tr>
<tr VALIGN="TOP">
 <td WIDTH="15%">目的</td>
 <td>过程的功能（不是实现功能的方法）。</td>
</tr>
<tr VALIGN="TOP">
 <td WIDTH="15%">假设</td>
 <td>其状态影响此过程的外部变量、控件或其他元素的列表。</td>
</tr>
<tr VALIGN="TOP">
 <td WIDTH="15%">效果</td>
 <td>过程对每个外部变量、控件或其他元素的影响效果的列表。</td>
</tr>
<tr VALIGN="TOP">
 <td WIDTH="15%">输入</td>
 <td>每个目的不明显的参数的解释。每个参数都应占据单独一行并有其内部注释。</td>
</tr>
<tr VALIGN="TOP">
 <td WIDTH="15%">返回</td>
 <td>返回值的解释。</td>
</tr>
 </table>
 请记住以下几点： <ul>
<li>每个重要的变量声明都应有内部注释，描述变量的用途。 </li>
<li>应清楚地命名变量、控件和过程，仅在说明复杂细节时需要内部注释。
</li>
<li>应在 Script 的开始部分包含描述该 Script
 的概述，列举对象、过程、运算法则、对话框和其他系统从属物。有时一段描述运算法则的假码是很有用的。
</li>
 </ul>

<h5>格式化代码</h5>

 应尽可能多地保留屏幕空间，但仍允许用代码格式反映逻辑结构和嵌套。以下为几点提示：
 <ul>
<li>标准嵌套块应缩进 4 个空格。 </li>
<li>过程的概述注释应缩进 1 个空格。 </li>
<li>概述注释后的最高层语句应缩进 4 个空格，每一层嵌套块再缩进 4
 个空格。例如： </li>
 </ul>


'*********************************************************
' 目的：返回指定用户在 UserList 数组中第一次出现的位置。
' 输入： strUserList(): 所查找的用户列表。
' strTargetUser: 要查找的用户名。
' 返回： strTargetUser 在 strUserList 数组中第一次出现时的索引。
' 如果目标用户未找到，返回 -1。
'*********************************************************

Function intFindUser (strUserList(), strTargetUser)
 Dim I ' 循环计数器。
 Dim blnFound ' 发现目标的标记。
 intFindUser = -1
 I = 0 ' 初始化循环计数器。
 Do While I <= Ubound(strUserList) and Not blnFound
 If strUserList(I) = strTargetUser Then
 blnFound = True ' 标记设为 True。
 intFindUser = I ' 返回值设为循环计数器。
 End If
 I = I + 1 ' 循环计数器加 1。
 Loop
End Function