Normas de codificación en Visual FoxPro

Resumen

Aplicar buenas normas de codificación es importante para el desarrollo de cualquier

proyecto; pero es particularmente importante cuando muchos desarrolladores están
trabajando en el mismo proyecto. Tener establecido pautas de codificación contribuye a
garantizar que el código es de alta calidad, con pocos errores y de fácil mantenimiento.

Estas normas o pautas se basan en años de desarrollo de aplicaciones con Visual FoxPro
y de aprendizaje de cuáles técnicas de codificación trabajan mejor. Además, muchos
conceptos han sido adaptados a partir de Code Complete (Microsoft Press, ISBN 1-
55615-484-4) escrito por Steve McConnell. Este libro, es considerado una de las guías
más importantes en prácticas de codificación. Puede que usted no esté de acuerdo con
éstas normas, no hay problemas. Para mí, estas normas han funcionado bien.

Normas de codificación

Convenciones de variables.

No utilice guiones bajos en nombres de variables. Mezclar mayúsculas y minúsculas

mejora la legibilidad. La primera letra de la variable debe indicar su alcance y debe ser
siempre minúscula. Trate de evitar el uso de variables públicas (PUBLIC) y privadas.
En su lugar utilice propiedades de los objetos de su aplicación, propiedades de
formularios y variables locales.

 l - Local
 g - Global
 p - Private
 t - Parameter

La segunda letra indica el tipo de dato.

 c - Character
 n - Numeric
 d - Date
 t - DateTime
 l - Logical
 m - Memo
 a - Array
 o - Object
 x - Indeterminate

Ejemplos de nombres de variables válidos:

lcFirstName
tdBeginDate
Tenga en mente el alcance de la variable. Preferiblemente deben utilizarse variables
locales (LOCAL). Las variables públicas (PUBLIC) deben evitarse tanto como sea
posible. Las declaraciones de variables, tales como: LOCAL lcMyVar se deben colocar
todas al inicio de la rutina a ejecutar, en lugar de dispersarlas por el código. Declare
todas las variables al inicio de la rutina, en lugar de entremezclarlas por todo el código y
asigne su valor predeterminado.

Forma incorrecta:

LOCAL lnMyNum
lnMyNum = 12

LOCAL lcMyString
lcMyString = "ABCD"

LOCAL lnCounter
lnCounter = 0

Forma correcta:

LOCAL lnMyNum, lcMyString, lnCounter

lnMyNum = 12
lcMyString = "ABCD"
lnCounter = 0

Convenciones para nombrar objetos.

Las primeras tres letras del nombre de un objeto deben ser utilizadas para indicar el tipo
del objeto.

 chk - Check box

 cbo - Combo box
 cmd - Command button
 cmg - Command Group
 cnt - Container
 ctl - Control
 cus - Custom
 edt - Edit box
 frm - Form
 frs - Form set
 grd - Grid
 grc - Grid Column
 grh - Grid Column Header
 img - Image
 lbl - Label
 lin - Line
 lst - List box
 olb - OLE Bound Control
 ole - OLE Object como un ActiveX Control
 opg - Option Group
  pag - Page
 pgf - Pageframe
 sep - Separator
 shp - Shape
 spn - Spinner
 txt - Text box
 tmr - Timer
 tbr - Toolbar

Normas para el código fuente:

1. Utilice abundantes espacios en blanco. Hará más legible su código.

2. Utilice tabuladores, en lugar de espacios para indentar.
3. Los comandos y funciones de Visual FoxPro deben escribirse en mayúsculas y
con la totalidad de sus letras, el resto del código debe estar escrito con
combinación de mayúsculas y minúsculas. Mantenga líneas cortas, tanto como
sea posible, para evitar desorden (line wrap) durante la impresión. Si una línea
de código, ocupa físicamente más de una línea, utilice las expresiones de unión
como primer carácter de la línea siguiente. Las expresiones de unión son del tipo
+, AND, OR, NOT, etc. Recuerde además, que la línea debe ser tan válida como
si fuera una sola línea. Coloque un espacio antes del punto y coma.

Ejemplos de malas separaciones de líneas:

lcCommand = "Hoy es Miércoles, 16 de Octubre de 2003" + ;

"Son las 2:00 PM"

IF ldBeginDate >= DATE() OR ;

ldEndDate >= DATE()

Ejemplos de buenas separaciones de líneas:

lcCommand = " Hoy es Miércoles, 16 de Octubre de 2003" ;

+ "Son las 2:00 PM"

IF ldBeginDate >= DATE() ;

OR ldEndDate >= DATE()
<li value="4">Por lo visto, cada uno combina las mayúsculas y minúsculas de
forma diferente. Aunque no existe vía correcta o incorrecta en este aspecto, si
hay algunas normas que ayudan a la legibilidad. Además, utilice expresiones
CASE en lugar de IF, cuando parezca que se pueden agregar posteriormente más
opciones, incluso si existen sólo dos opciones en el momento en que es escrito el
código o, para liberarse de las instrucciones IF, ELSE, IF. Separe cada CASE
por una línea en blanco. El comentario para el CASE debe ir por debajo del
mismo.

Forma incorrecta:

DO CASE
* Este es el comentario para el caso 1
CASE lnCount = 1
lcRetVal = "Uno"
 * Este es el comentario para el caso 2
CASE lnCount = 2
lcRetVal = "Dos"
* Este es el comentario para otherwise
OTHERWISE
lcRetVal = "Otro"
ENDCASE

Forma correcta:

DO CASE
CASE lnCount = 1
* Este es el comentario para el caso 1
lcRetVal = "Uno"
CASE lnCount = 2
* Este es el comentario para el caso 2
lcRetVal = "Dos"
OTHERWISE
* Este es el comentario para otherwise
lcRetVal = "Otro"
ENDCASE
<ol start="5">
 Trate de evitar macro sustitución. A veces la macrosutitución es la única vía para
lograr algo. Asegúrese de documentar, por qué utiliza macrosustitución y cuál es el
propósito del código. En la mayoría de los casos, la macrosustitución hace que el código
sea menos legible. Utilice la función EVALUATE(). Si es posible, pero nuevamente los
comentarios son importantes para ayudar a leer el código.
 Evite utilizar STORE.
 Utilice "[]" en lugar de paréntesis en los arreglos. Así, el código es más legible.
 Coloque espacios entre los operadores matemáticos. Esto mejora la legibilidad.
 Utilice paréntesis cuando llame métodos o funciones, incluso, si no pasa ningún
parámetro.
 Evite el uso de m. a la izquierda del signo igual. Esto mejorará el rendimiento.
 Al concatenar cadenas, coloque la variable a la izquierda del signo +. Esto mejorará
el rendimiento.

Normas para comentar código

Los comentarios son parte importante de cualquier aplicación. Utilícelos

abundantemente. Los comentarios deben explicar por qué se han hecho algunas cosas e
indicar cuáles son las líneas de código que están afectadas. Debe explicar solamente
cómo se hizo algo, en caso de estar utilizando complejos algoritmos o cálculos.

No emplee comentarios al final de las líneas con &&. Cada comentario debe ocupar una
línea propia.

Encabezados de programa, método y procedimiento.

Los encabezados de programa, método y procedimiento deben indicar el nombre de la

rutina, la fecha en que fue creada originalmente, el autor y una descripción del objetivo
del procedimiento o método. En caso de existir parámetros y valores devueltos, incluya
una descripción de los mismos. Para los métodos, incluya la jerarquía de objetos.
Ejemplo 1:

*********************************************************
* Método........: frmQueue.cmdNext.Click
* Descripción...: Displays the next item in the selected queue
* Fecha.........: 01-Oct-2001
* Autor.... ....: Fred Flintstone
*********************************************************
* Modification Summary
*
*********************************************************

Ejemplo 2:

*********************************************************
* Función......: CalcIntrest
* Descripción...: Calculate the interest in dollars on the loan
* Parámetros....: tnBalance: Required: The balance amount
* : tnRate: Required: The interest rate to apply
* Devuelve......: Numeric: The dollar amount of the interest
* Fecha.........: 01-Oct-2001
* Autor.........: Bullwinkle J. Moose
*********************************************************
* Modification Summary (Resumen de modificaciones)
*
*********************************************************

Comentar modificaciones

Es importante poner comentarios al hacer modificaciones para saber cuáles fueron las
modificaciones realizadas, y por qué las realizó. La sección Modification Summary
(Resumen de modificaciones) en el encabezado explicará por qué, cuándo y por quién
fueron realizadas las modificaciones. En cada lugar del código, donde fue realizada una
modificación, debe comentar el código viejo e indicar cuál es el código nuevo que fue
añadido. Cada modificación debe ser numerada. Los cambios pueden ser borrados
después de un año; pero el Resumen de modificaciones debe permanecer.

Ejemplo:

*********************************************************
* Modification Summary
*
* /01 05-Oct-2001 George Jetson
* Changed interest calculation to include a date range factor.
* /02 10-Oct-2001 Tennessee Tuxedo
* 1. Added code to handle interest on widgets. The calculation is
different.
* 2. Changed the return value from numeric to character.
*********************************************************
*/01 lcNote = "This is the old line commented out "
*/01
lcNote = "This is the new line of code. "
*/02-1 lnInterest = a * b
*/02-1 lnInterest = lnInterest / 43
*/02-1 - Begin - Multiple lines are being added, so indicate they
start here
IF UPPER(tcIntType) = "WIDGETS "
 lnInterest = a * c
ELSE
lnInterest = a * b
lnInterest = lnInterest / 43
ENDIF
*/02-1 - End

Las líneas de comentario deben indentarse al mismo nivel del código.

Este ejemplo es incorrecto:

IF lnTotalInterest = 0
*/01 � Begin
FOR lnCount = 1 TO lnTotal
lnTotalInterest = lnTotalInterest + laLoans[lnCount, 2]
ENDFOR
*/02 � End
ENDIF

Este ejemplo es correcto:

IF lnTotalInterest = 0
*/01 � Begin
FOR lnCount = 1 TO lnTotal
lnTotalInterest = lnTotalInterest + laLoans[lnCount, 2]
ENDFOR
*/02 � End
ENDIF

Al comentar líneas que continúan, hay que comentar cada línea física.

Incorrecto:

*/01 lcString = "Esta cadena contiene mucho texto porque es un " ;

+ "ejemplo de una línea verdaderamente larga "

Correcto:

*/01 lcString = "Esta cadena contiene mucho texto porque es un " ;

*/01 + "ejemplo de una línea verdaderamente larga "

Normas para interfaz de usuario

Normas generales para interfaz de usuario (UI)

Cuando sea posible, la interfaz de usuario debe cumplir con las directivas de Windows
Standards descritas en el libro  "Microsoft Windows User Experience ", Microsoft
Press, ISBN 0-7356-0566-1. Este libro se encuentra disponible en:
http://msdn.microsoft.com/library/en-us/dnwue/html/welcome.asp. Tenga en mente
todo el tiempo al usuario. Mientras más sencilla sea la funcionalidad para el usuario,
mejor será la aplicación. Esto puede significar que el código que está detrás de esta
funcionalidad es más complejo.

Formularios de entrada de datos

 1. Todos los campos aptos para entrada deben utilizar Select On Entry.
2. Los campos numéricos deben ser formateados con comas y signos negativos
cuando sea necesario.
3. Si un campo es de sólo lectura, establezca la propiedad TabStop en .F.,
Establezca la propiedad ReadOnly a .T. o la propiedad Enabled a .F., según sea
el caso. La propiedad ReadOnly se utiliza cuando el campo nunca es
modificable. La propiedad Enabled se utiliza cuando el campo es modificable
cuando se cumple una determinada condición (es evaluada a .F.)
4. Utilice la barra de estado para mostrar un mensaje al usuario que indique el
propósito del campo.
5. Muestre siempre los valores predeterminados, en los casos en que se aplique.
6. Inhabilite (Enabled = .F.) los objetos cuando sea necesario. Esto proporciona
indicación visual al usuario de que el objeto no puede ser modificado en ese
momento.

Mensajes

1. No utilice WAIT WINDOW para mostrar mensajes importantes al usuario. Es

muy fácil que el usuario no note el mensaje. En su lugar utilice
MESSAGEBOX. Incluya siempre el icono apropiado en el cuadro de mensaje
(message box). Evite la utilización del parámetro TIMEOUT, ya que el usuario
puede perder información importante.
2. Utilice la barra de estado para mostrar ayuda en línea para el objeto actual, ya
sea en un formulario o un menú.

Objetos de formulario

1. Text box. (cuadros de texto) El cuadro de texto es el control más comúnmente

utilizado. Puede contener valores de caracteres, numéricos o fecha.
2. Check box. (casilla de verificación) La casilla de verificación es un control
sencillo que está establecido en ON u OFF. Son utilizadas típicamente para
indicar un estado de Sí o No.
3. Command button. (Botón de comando) El botón de comandos es utilizado para
iniciar una acción. Los botones más comúnmente utilizados son OK (Aceptar) y
Cancel (Cancelar). Algunas veces los botones de comandos son agrupados en los
command group (grupos de comandos). Intente evitar los grupos de comandos,
los botones individuales son más fáciles de mantener.
4. Option button. (Botón de opción) En ocasiones se les llama radio button. Se
utiliza para indicar que el usuario puede seleccionar una opción de un grupo de
opciones. Los botones de opciones son frecuentemente agrupados en Option
group (grupo de opciones). Esto simplifica el código para el proceso de
selección. Se recomienda que los grupos de opciones se utilicen en lugar de los
botones de opciones. Los grupos de opciones deben ser preferiblemente
ordenados verticalmente antes que horizontalmente.
5. Drop-down list. (Lista desplegable) Una lista desplegable permite al usuario
hacer una selección de una lista de varios objetos, como con un botón de opción.
Sin embargo, la lista desplegable requiere de menos espacio en pantalla.
6. Combo box. (Cuadro combinado) Los cuadros combinados se identifican como
un textbox en una flecha hacia abajo. Se llama cuadro combinado, porque es una
 combinación de un cuadro de texto y una lista desplegable. El usuario puede
escribir un nuevo valor o seleccionarlo de la lista.
7. List box. (Cuadro de lista) Un cuadro de lista puede ser utilizado uno o varios
objetos de una lista.
8. Spinner. Un control spinner es una especie de textbox con flechas hacia arriba y
hacia abajo. Es utilizado normalmente para datos numéricos. El número aumenta
o disminuye al hacer clic en las flechas o el usuario puede introducir un valor
específico.
9. Edit box. (Cuadro de edición) Un cuadro de edición se comporta de forma
parecida al textbox; pero normalmente es utilizado para campos memo. Un
editbox puede tener barras de desplazamiento y deslizamiento de filas (word
wrap)