Convenciones de codificación de VBScript

Las convenciones de codificación son sugerencias que pueden ayudarle a escribir código mediante Microsoft Visual Basic Scripting Edition. Las convenciones de codificación pueden incluir:

Convenciones de nomenclatura para objetos, variables y procedimientos
Convenciones de comentarios
Formato de texto y directrices de sangrías

La razón principal para utilizar un conjunto de convenciones de codificación es estandarizar la estructura y estilo de codificación de una secuencia de comandos o de un conjunto de secuencias de comandos de manera que usted y otros puedan leer y entender el código fácilmente. Utilizar buenas convenciones de código da como resultado código de origen preciso, legible, coherente con otras convenciones de lenguaje e intuitivo.

Convenciones de nomenclatura para constantes

Las versiones anteriores de VBScript no tenían ningún mecanismo para crear constantes definidas por el usuario. Las constantes, si se utilizaban, se implementaban como variables y se distinguían de otras variables utilizando todos los caracteres en mayúscula. Las palabras múltiples se separaban utilizando el carácter de subrayado. Por ejemplo:

USER_LIST_MAX
NEW_LINE

Aunque esto es aún una forma aceptada de identificar sus constantes, quizá desee utilizar un esquema de nomenclatura alternativo, ahora que puede crear verdaderas constantes mediante la instrucción Const. Esta convención utiliza un formato mixto de mayúsculas y minúsculas en el que los nombres de constante tienen un prefijo "con" (constante). Por ejemplo:

conYourOwnConstant

Convenciones de nomenclatura para variables

Para mejorar la legibilidad y coherencia, utilice los siguientes prefijos con nombres descriptivos para variables en su código VBScript.

Subtipo	Prefijo	Ejemplo
Boolean	bln	blnFound
Byte	byt	bytRasterData
Date (hora)	dtm	dtmStart
Double	dbl	dblTolerance
Error	err	errOrderNum
Integer	int	intQuantity
Long	lng	lngDistance
Object	obj	objCurrent
Single	sng	sngAverage
String	str	strFirstName

Ámbito de la variable

Las variables deben definirse siempre con el menor ámbito posible. Las variables de VBScript pueden tener el siguiente ámbito.

Ámbito	Donde se declara la variable	Visibilidad
Nivel de procedimiento	Procedimiento Event, Function o Sub	Visible en el procedimiento donde se declara
Nivel de secuencia de comandos	Sección HEAD de una página HTML, fuera de cualquier procedimiento	Visible en cada procedimiento de la secuencia de comandos

Prefijos de ámbito variable

A medida que aumenta el tamaño de la secuencia de comandos, aumenta el valor de la posibilidad de diferenciar el ámbito de las variables. Esto lo proporciona un prefijo de ámbito de una letra que precede al prefijo de tipo, sin aumentar el tamaño de los nombres de variable.

Ámbito	Prefijo	Ejemplo
Nivel de procedimiento	Ninguno	dblVelocity
Nivel de secuencia de comandos	s	sblnCalcInProgress

Nombres descriptivos de variable y de procedimiento

El cuerpo de una variable o procedimiento debe utilizar una combinación de mayúsculas y minúsculas y debe ser tan descriptivo como sea necesario. Además, los nombres de procedimiento deben comenzar por un verbo, como InitNameArray o CloseDialog.

Para términos utilizados con frecuencia o largos, se recomiendan las abreviaturas estándar para ayudar a mantener una longitud razonable del nombre. En general, los nombres de variable mayores de 32 caracteres pueden ser difíciles de leer. Cuando utilice abreviaturas, asegúrese de que son coherentes a lo largo de toda la secuencia de comandos. Por ejemplo, cambiar aleatoriamente entre Cnt y Count dentro de una secuencia o un conjunto de secuencias de comandos puede inducir a confusión.

Convenciones de nomenclatura para objetos

La siguiente tabla muestra las convenciones recomendadas para los objetos con los que puede encontrarse mientras programa en VBScript.

Tipo de objeto	Prefijo	Ejemplo
Panel 3D	pnl	pnlGroup
Botón animado	ani	aniMailBox
Casilla de verificación	chk	chkReadOnly
Cuadro combinado, cuadro de lista desplegable	cbo	cboEnglish
Botón de comando	cmd	cmdExit
Diálogo común	dlg	dlgFileOpen
Marco	fra	fraLanguage
Barra de desplazamiento horizontal	hsb	hsbVolume
Imagen	img	imgIcon
Etiqueta	lbl	lblHelpMessage
Línea	lin	linVertical
Cuadro de lista	lst	lstPolicyCodes
Botón de número	spn	spnPages
Cuadro de texto	txt	txtLastName
Barra de desplazamiento vertical	vsb	vsbRate
Control deslizante	sld	sldScale

Convenciones de comentarios de código

Todos los procedimientos deben comenzar por un breve comentario que describa lo que hacen. Esta descripción no debe describir los detalles de implementación (cómo lo hace) porque a menudo cambia a lo largo del tiempo y provoca un trabajo de mantenimiento de comentarios innecesario, o lo que es peor, comentarios incorrectos. El propio código y cualquier comentario de línea necesarios describen la implementación.

Los argumentos que se pasan a un procedimiento deben describirse cuando su propósito no es evidente y cuando el procedimiento espera que los argumentos estén comprendidos en un intervalo específico. Los valores de retorno para las funciones y variables que cambia un procedimiento, especialmente a través de argumentos de referencia, deben también describirse al comienzo de cada procedimiento.

Los comentarios del encabezado del procedimiento deben incluir los siguientes encabezados de sección. Para ver un ejemplo, consulte la sección siguiente "Dar formato a su código".

Encabezado de sección	Contenido del comentario
Propósito	Lo que el procedimiento hace (no cómo).
Suposiciones	Lista de cualquier variable o control externo, o cualquier otro elemento cuyo estado afecte a este procedimiento.
Efectos	Lista del efecto del procedimiento en cada variable o control externo, u otro elemento.
Entradas	Explicación de cada argumento que no sea evidente. Cada argumento debe estar en una línea distinta con comentarios de línea.
Valores de retorno	Explicación del valor devuelto.

Recuerde los siguientes puntos:

Cada instrucción de variable importante debe incluir un comentario de línea que describa el uso de la variable que se declara.
Las variables, controles y procedimientos deben tener un nombre lo suficientemente claro para asegurar que los comentarios de línea sólo se necesiten para detalles de implementación compleja.
Al comienzo de su secuencia de comandos, debe incluir una introducción que describa la secuencia de comandos, que enumere los objetos, procedimientos, algoritmos, cuadros de diálogo y otras dependencias del sistema. A veces, puede ser útil una porción de pseudocódigo que describa el algoritmo.

Dar formato al código

Se debe conservar el espacio de pantalla lo más posible, siempre que permita dar formato al código para reflejar la estructura lógica y el anidamiento. Aquí tiene unas cuantas sugerencias:

Los bloques anidados estándar deben tener una sangría de cuatro espacios.
Para comentarios generales de un procedimiento deben tener una sangría de un espacio.
Las instrucciones de nivel superior que sigan a los comentarios generales deben tener una sangría de cuatro espacios y otros cuatro espacios por cada bloque anidado.

El siguiente código utiliza los convenciones de codificación de VBScript.

'*********************************************************
' Propósito: ubica la primera aparición de un usuario  
'          especificado en la matriz UserList.
' Entrada: strUserList(): la lista de usuarios que se ha de buscar.
'          strTargetUser: el nombre del usuario que se ha de buscar.
' Salida: el índice de la primera aparición de strTargetUser 
'          en la matriz strUserList. 
'          Si no se encuentra el usuario buscado, devuelve -1.
'*********************************************************
Function intFindUser (strUserList(), strTargetUser)
   Dim i                 ' Contador de bucle.
   Dim blnFound         ' Indicador de destino encontrado
   intFindUser = -1
   i = 0                     ' Inicializar contador de bucle
   Do While i <= Ubound(strUserList) and Not blnFound
      If strUserList(i) = strTargetUser Then 
         blnFound = True   ' Establecer indicador como True
         intFindUser = i   ' Establecer valor de ret. como cont. de bucle
      End If
      i = i + 1         ' Incrementar contador de bucle
   Loop
End Function