jueves, junio 26, 2014

FoxBin2Prg: Guía rápida de uso y configuración

[2015/04/18: Actualizado hasta FoxBin2Prg v1.19.42]

Por: Fernando D. Bozzo

En el caso de que no sepas de qué va esto porque sea la primera vez que entras aquí, te lo resumo:

FoxBin2Prg es un programa Open Source que forma parte del proyecto VFPX en CodePlex, esta hecho en Visual FoxPro 9 SP2 y pretende sustituir a TwoFox y al scctext.prg que viene con Visual FoxPro y que se usa para realizar la conversión de los binarios de VFP 9 (scx, vcx, etc) a texto estilo-prg, con la diferencia de que FoxBin2Prg es bidireccional, o sea que desde el texto puede regenerar los binarios.

Aunque este programa es un PRG, también está compilado como un EXE para que se pueda vincular a otras herramientas, como el explorador de archivos o herramientas SCM (control de código fuente) como Plastic, SourceSafe, etc., además el EXE es m´s rápido y tiene incluido todos los archivos necesarios.


Breve reseña del problema a resolver


Un problema de los binarios de Visual FoxPro (scx, vcx, etc) es justamente ese, que su código fuente está metido en tablas DBF (sí, los scx, vcx y demás son DBF renombrados) y esto dificulta enormemente poder trabajar con ellos de forma más libre y sobre todo dificulta poder integrarlo en herramientas de control de código fuente, y en parte esto es una de las causas de que muchos programadores FoxPro no usen herramientas de control de código.
A todos los efectos, desde fuera estos arhivos son binarios, y como tales, son susceptibles de corromperse, y de hecho lo hacen, y cuando lo hacen hay una alta probabilidad de perder todo o parte del código fuente.

Lo que se hizo en su momento (años 90) para minimizar este problema, fue convertir estos binarios a representaciones de texto, para lo cual, el más conocido de esos programas (scctext.prg) hacía un volcado de los campos memo internos de los forms, clases y demás a un txt con extensión sca, vca, etc, pero casi sin ningún formateo que permitiera poder verlo mejor y analizarlo, y así ha sido hasta la llegada de un nuevo programa en enero de 2014, FoxBin2Prg, que justamente pretende cubrir todas esas carencias mediante la generación de vistas modificables de texto que son un 99% código PRG para los binarios que tienen código fuente y que cualquier programador Fox entiende; y pseudo-XML para los demás, pero con un detalle importante: con este texto generado se puede volver a reconstruir el binario original, lo que permite realizar todas las operaciones de manejo de código que se suelen hacer con una herramienta SCM, incluyendo el diff y el merge, que es la operación más compleja en un entorno de desarrollo.


¡La Capitalización de nombres de archivo importa!


Es necesario conocer exactamente qué hace FoxBin2Prg, para luego poder elegir cómo, cuándo y por qué hacerlo.

FoxBin2Prg no solo genera una vista de texto de los binarios y regenera los binarios desde la vista de texto, sino que también capitaliza los programas que convierte para normalizarlos, para lo que se integra con otro programa específico llamado filename_caps.exe, y que también puede usarse por separado.

La importancia de esta capitalización radica en que cuando se usan ciertos programas o sistemas multiplataforma para gestión de código, como CVS, Subversion, Git, Plastic y otros, un archivo.así es distinto que un Archivo.ASÍ, ya que Windows es prácticamente el único Sistema Operativo que no distingue entre ambos, pero Mac, Linux, Unix, BeOS y otros sí, y los consideran como dos archivos distintos.

Estas diferencias en los nombres de archivo pueden provocar toda clase de problemas, desde errores que impidan trabajar o sincronizar con el SCM (por ejemplo GitHub, CVS, etc), hasta la sustitución de archivos por versiones erróneas.


¿Qué contiene el proyecto?:


El proyecto contiene todos los archivos fuentes, pero para su uso sólo se requieren ciertos archivos, que varían dependiendo de si se usa el EXE o el PRG.


Versión EXE (más compacta y rápida):
  • FoxBin2Prg.exe => Conversor principal con todo dentro
  • FoxBin2Prg.cfg => Configuración del Conversor



Versión PRG (requiere más archivos y es algo menos rápida): 

  • FoxBin2Prg.prg => Conversor principal
  • Props_*.txt => 27 Archivos para evaluación y ordenamiento de propiedades

Archivos necesarios en ambas versiones:
  • FoxBin2Prg.cfg.txt => Archivo modelo para usar de configuración del conversor
  • filename_caps.exe => Gestor de capitalización de nombres de archivo
  • filename_caps.cfg => Configuración del Gestor de capitalización
  • Convert_VFP9_BIN_2_PRG.vbs => Script para conversión masiva de Binario a Tx2, y mostrando mensaje de finalización de proceso. (Opcional, se puede reemplazar por FoxBin llamado con el parámetro BIN2PRG)
  • Convert_VFP9_PRG_2_BIN.vbs => Script para conversión masiva de Tx2 a Binario, y mostrando mensaje de finalización de proceso. (Opcional, se puede reemplazar por FoxBin llamado con el parámetro PRG2BIN)
  • Normalize_FileNames.vbs =>  Script para capitalización masiva de archivos
  • VFP9_FoxBin2Prg.vbs => Script para invocar a FoxBin2Prg.exe, pero mostrando mensaje de finalización de proceso. (Opcional, se puede reemplazar por FoxBin llamado con el parámetro SHOWMSG)


Internacionalización (localización)


Desde la versión v1.19.38 la selección de lenguaje es automática y se basa en la función VERSION(3), y se puede cambiar en el archivo de configuración foxbin2prg.cfg usando la nueva opción "Language".

Los valores adminitos son: ES  (Español), EN (Inglés), DE (Alemán) y FR (Francés) y si se indica cualquier otro o el predeterminado no es uno de estos, se seleccionará automáticamente Inglés (EN).



Vale, y ahora, ¿cómo se usa?


Para usar FoxBin2Prg desde el Explorador de archivos, puede crear 3 accesos directos de FoxBin2Prg.exe (click-derecho / crear acceso directo) y moverlos a la carpeta "SendTo" en su perfil de Windows (que normalmente está en C:\Documents and settings\<usuario>\SendTo o en C:\Users\usuario\<usuario>\SendTo), así podrá "enviar" el archivo elegido (pjx,pj2,etc) a la opción seleccionada, y hacer conversiones-al-vuelo, luego renombre esos accesos directos y modifíquelos como sigue (asegúrese de que puede ver las extensiones de archivos del sistema):

Nombre----------------------  Click-Derecho/Propiedades/destino----------------
FoxBin2Prg - Binary2Text.lnk  <path>\foxbin2prg.exe "BIN2PRG-INTERACTIVE"
FoxBin2Prg - Text2Binary.lnk  <path>\foxbin2prg.exe "PRG2BIN-INTERACTIVE"
FoxBin2Prg.lnk                <path>\foxbin2prg.exe "INTERACTIVE"

  • Con la opción "BIN2PRG" o "PRG2BIN", puede procesar directorios o archivos individuales
  • Con FoxBin2Prg.exe solamente, puede procesar archivos individuales
  • Con la opción "INTERACTIVE", un mensaje de confirmación será mostrado cuando termine, y los errores encontrados serán mostrados automáticamente también


¡Atención! No copiar los programas en la carpeta SendTo, sólo deben ponerse los "accesos directos" de los programas, ya que internamente tienen la ruta completa del programa original.


Casos de uso:

- Si se quiere convertir sólo 1 archivo binario a texto, entonces se debe hacer click-derecho en el archivo (scx, vcx, etc) y elegir Enviar a => FoxBin2Prg

- Si se quiere convertir sólo 1 archivo texto a binario, entonces se debe hacer click-derecho en el archivo (sc2, vc2, etc) y elegir Enviar a => FoxBin2Prg

- Si se quieren convertir los archivos binarios a texto de un directorio, entonces se debe hacer click-derecho en el directorio y elegir Enviar a => FoxBin2Prg - Binary2Text

- - Si se quieren convertir los archivos de texto a binario de un directorio, entonces se debe hacer click-derecho en el directorio y elegir Enviar a => FoxBin2Prg - Text2Binary

- Si se quieren capitalizar los archivos de un directorio, entonces se debe hacer click-derecho en un directorio y elegir Enviar a => Normalize_FileNames



El caso de uso normal sería el siguiente:

- Se trabaja un form, una clase, etc., en una sesión de FoxPro hasta que se termine y se cierra el form

- Clear all en la ventana de comandos

- En el explorador de archivos se elije el form (o clase, etc) y se convierte a texto

- Luego se elige el archivo de texto recién generado y se vuelve a convertir a binario

Listo!



Configuración

El Gestor de Capitalización por defecto está configurado para respetar la capitalización de los nombres de archivo y pasar las extensiones a minúsculas, y normalmente con eso es suficiente. Pero si se quiere controlar más, mirar dentro del archivo filename_caps.cfg que está más detallado y con algunos ejemplos.

La configuración por defecto es esta:

filemask=*.*:N.L

El Conversor por defecto está configurado para generar las extensiones xx2, soportar la conversión bidireccional de todas menos los DB2 (por seguridad, pero se puede cambiar) y dejar vacíos los Timestamps e ID's de registro.

[2015/04/18 - v1.19.42 >>]
En el directorio de instalación hay un archivo de configuración llamado foxbin2prg.cfg.txt donde están detallados los valores por defecto en Inglés y Español, y más abajo están las configuraciones modificables.
Este archivo, si se le quita la extensión .txt (foxbin2prg.cfg), se puede usar como modelo para crear configuraciones personalizadas por directorio, aprovechando la herencia de CFGs entre directorios padre/hijo.

FoxBin2Prg.cfg - Si no se proporcionan valores, estos son los predeterminados Detalle y valores soportados
extension: xx2 Las extensiones por defecto de FoxBin2Prg terminan en '2'
ShowProgressbar: 1 1=Mostrar barra de progreso por defecto en procesamiento multi-archivo, 0=No mostrar PB
DontShowErrors: 0 Mostrar mensajes de error por defecto
NoTimestamps: 1 Vaciar Timestamps por defecto para minimizar diferencias
Debug: 0 No Activar <archivo>.Log por defecto
ExtraBackupLevels: 1 Por defecto 1 BAK es creado. Con esto puede crear más .N.BAK, o ninguno si indica 0.
ClearUniqueID: 1 0=Mantener UniqueID, 1=Borrar Unique ID. Util para Diff y Merge
OptimizeByFilestamp: 0 1=Optimizar la regeneración de archivos dependiendo del timestamp de archivo, 0=No optimizar (más seguro si se usa para merge o para editar el tx2)
ClearDBFLastUpdate: 1 1=No mantener la fecha LastUpdate de los DBFs, 0=Mantenerla
DropNullCharsFromCode: 1 1=Quitar NULLs del código fuente, 0=Dejar los NULLs en el código
Language: (auto) Lenguage de los mensajes mostrados y Logs. EN=Inglés, FR=Francés, ES=Español, DE=Alemán, No definido = AUTOMATICO [DEFAULT]
XXX_Conversion_Support: N 0=Sin soporte, 1=Generar solo TXT (Diff), 2=Regenerar BINARIOS (Merge), 4=Generate TXT with DATA for DIFF (DBF only)
PJX_Conversion_Support: 2 Ver XXX_Conversion_Support
VCX_Conversion_Support: 2 Ver XXX_Conversion_Support
SCX_Conversion_Support: 2 Ver XXX_Conversion_Support
FRX_Conversion_Support: 2 Ver XXX_Conversion_Support
LBX_Conversion_Support: 2 Ver XXX_Conversion_Support
MNX_Conversion_Support: 2 Ver XXX_Conversion_Support
DBC_Conversion_Support: 2 Ver XXX_Conversion_Support
DBF_Conversion_Support: 1 Ver XXX_Conversion_Support >> FoxBin2Prg tiene soporte bi-direccional para convertir DBF, pero no mantiene los datos. Usar con cuidado.
DBF_Conversion_Included: * Si DBF_Conversion_Support:4, se pueden indicar múltiples máscaras de archivo: www,fb2p_free.dbf
DBF_Conversion_Excluded: Si DBF_Conversion_Support:4, se pueden indicar múltiples máscaras de archivo: www,fb2p_free.dbf
UseClassPerFile: 0 0=Una archivo librería tx2, 1=Múltiples archivo.clase.tx2, 2=Múltiples archivo.clasebase.clase.tx2, incluyendo DBCs y sus miembros
RedirectClassPerFileToMain: 0 0=No redireccionar a archivo.tx2, 1=Redireccionar a archivo.tx2 cuando se seleccione archivo.clase.tx2
ClassPerFileCheck: 0 0=No verificar la inclusión de archivo.clase.tx2, 1=Verificar la inclusión de archivo.clase.tx2

[<<]



Exportar datos para Diff (DBF_Conversion_Support:4)


Con esta configuración se pueden exportar los datos de las tabla, y con las siguientes configuraciones se puede hilar más fino, eligiendo qué tablas sí, cuáles no, y con qué ordenamiento y filtro.

DBF_Conversion_Included: <filemask>[ ,<filemask> [ , ... ] ]
DBF_Conversion_Excluded: <filemask>[ ,<filemask> [ , ... ] ]

Ejemplo de las máscaras <filemask>, separadas por coma:

DBF_Conversion_Included: PET*.*, ??ME.DBF, ???.DBF, ?.*


Si se quisieran filtrar los datos de una tabla llamada mitabla.dbf  para solo exportar los registros cuyo campo is_initial = .T. y se desea exportar ordenado por cust_order, habría que crear un archivo cfg en el mismo directorio de la tabla, así:

mitabla.dbf.cfg:
DBF_Conversion_Order: cust_order
DBF_Conversion_Condition: is_initial = .T

Nota: En DBF_Conversion_Order se puede poner cualquier expresión FoxPro válida para ordenar


[2015/04/18 - v1.19.42 >>]

Generar una clase por archivo (UseClassPerFile:1 ó 2)


Desde la v1.19.37 se puede configurar FoxBin2Prg para generar las clases de una librería en archivos independientes, si se pone el seteo UseClassPerFile:1 en foxbin2prg.cfg, lo que generará archivos con la nomenclatura de TwoFox (libreria.nombreclase.tx2)

Por defecto, si luego se elige uno de esos archivos de clases (libreria.nombreclase.tx2) y se intenta regenerar el binario, se creará una nueva librería archivo.clase.vcx, que en algún caso puede ser útil si se quieren separar algunas clases de una librería.

Desde la v1.19.42 se puede usar el nuevo valor "2" para UseClassPerFile, que a diferencia del anterior genera archivos con una nomenclatura libreria.clasebase.nombreclase.tx2 que es más explícita y por tanto más útil para poder identificar rápidamente las clases visuales de las no visuales, por ejemplo.

Además con "2" se aplicará esta división en archivos individuales también a los DBC, donde la nomenclatura de los miembros será nombrebdd.tipo.nombre.dc2, por ejemplo: nombrebdd.connection.cnxoracle.dc2 o nombrebdd.table.clientes.dc2

En el caso de que que siempre se quiera que se regenere la librería original, sin importar cuál de sus partes se elija, se debe usar el seteo RedirectClassPerFileToMain:1, lo que redirigirá las peticiones al archivo principal.

Cuando se ensamblan las librerías desde las partes archivo.clase.tx2, no se verifica si esa parte realmente corresponde a la librería, lo ue permite anexar nuevas clases con solo ponerle la nomenclatura adecuada.

En el caso de que se quiera asegurar de que solamente las clases originales se ensamblen en la librería VCX, se puede usar el seteo ClassPerFileCheck:1, lo que comprobará que los archivos encontrados figuren en la lista interna del archivo principal de cabecera. 
[<<]

Está generando un archivo de error .ERR, ¿que hago?


Pues lo primero es abrir ese archivo y ver qué error muestra. Es probable que diga algo como esto:

Error 1098, El archivo [C:\DESA\foxbin2prg\tst1.sct] no está soportado

Y es correcto, porque se debió elegir el que termina en 'x' (scx, vcx, etc)

Para cualquier otro tipo de error, por favor, reportármelo así lo analizo.



Una cosa más


Aquí no hablé de la integración y uso con ninguna herramienta SCM, porque la idea era que conozcan el uso de este programa en solitario, y porque no todo el mundo pretende usar una herramienta SCM (control de código fuente)

Para el uso integrado con otras herramientas, ya he comentado sobre la integración con PlasticSCM en esta nota sobre su instalación y en esta nota sobre su uso en ramas, y en futuras notas podrá ser con otras herramientas SCM.



Eso es todo!



Si te interesa conocer más detalles, aquí unos links:
- FoxBin2Prg: El sucesor mejorado del scctext
- FoxBin2Prg: Detalle de vistas, datos de uso, configuraciones y más
- FoxBin2Prg: Descarga de VFPx
- FoxBin2Prg: Descarga de GitHub

miércoles, junio 25, 2014

Nueva versión v2.4.19 de las herramientas Visual FoxPro 9 para PlasticSCM (Incluye FoxBin2Prg.exe v1.19.25)

Por: Fernando D. Bozzo

Está liberada la versión v2.4.19 de las herramientas Visual FoxPro 9 para PlasticSCM, con los siguientes cambios:




Estas herramientas son un grupo de scripts vbs y programas Visual FoxPro 9 que se configuran dentro de PlasticSCM para poder invocar a FoxBin2Prg (incluye solo el EXE) desde dentro de la interfaz de Plastic.

El README.txt explica como se configura en Inglés y Español.

Nota: Los fuentes del proyecto FoxBin2Prg y el historial de ambios, están en CodePlex, en este link.


Como actualizar las existentes:
Con descargarlas y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link de descarga:
https://github.com/fdbozzo/foxpro_plastic_diff_merge


Saludos!

Nueva versión v1.19.25 de FoxBin2Prg (Mejoras y nueva configuración)

Por: Fernando D. Bozzo

Está liberada la versión v1.19.25 de FoxBin2Prg con los siguientes cambios:

  • Cuando se  procesa uno o múltiples archivos con los scripts, al finalizar mostrar un mensaje de estado indicando si se encontraron errores, y si hay, mostrar un log de los mismos (Pedro Gutiérrez M.)
    > Hasta la versión anterior solo se podían encontrar los errores viendo si se generaban archivos .ERR individuales, pero ahora se recopila en un log que se muestra automáticamente al finalizar el proceso.
    .
  • ClearUniqueID es True por defecto en los archivos tx2
    > Este valor ya estaba preconfigurado en el archivo foxbin2prg.cfg, pero ahora está puesto por defecto dentro del programa.
    .
  • OptimizeByTimestamp es False por defecto, para evitar posibles modificaciones automáticas de VFP al abrir un form o clase
    > Cuando se abre un form o una librería, por ejemplo para ver o checkear algo, y se sale sin guardar, a veces FoxPro cambia igualmente el timestamp del archivo y puede que actualice algún valor binario interno, lo que puede provocar que si está habilitada esta optimización, cuando se quiera regenerar el binario, no se pueda por tener un timestamp más nuevo que el tx2, y a la larga podría provocar que se pierda alguna modificación, y por eso ahora se desactiva por defecto. Se puede reactivar desde el archivo de configuración foxbin2prg.cfg poniendo OptimizeByTimestamp: 1.
    .
  • Nuevo switch AllowMultiConfig habilitado por defecto, que permite usar archivos CFG por directorio, haciendo averride del CFG principal (Mario Peschke)
    > Esta nueva característica, habilitada por defecto, permite tener directorios con configuraciones específicas. Por ejemplo, se podría configurar un directorio para que contenga las estructuras de las tablas e índices, y tener habilitado el switch DBF_Conversion_Suppport: 2 sólo allí para regenerar los DBFs e Indices.
    .
  • Agregado el soporte del switch AllowMultiConfig en foxbin2prg.cfg
    > Este es el switch del archivo de configuración foxbin2prg.cfg de lo comentado en el punto anterior.


Como actualizar el FoxBin2Prg existente:
Con descargar el zip y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link  de descarga:
https://vfpx.codeplex.com/releases/view/116407


 Saludos!

domingo, junio 15, 2014

Nueva versión v2.4.18 de las herramientas Visual FoxPro 9 para PlasticSCM (Incluye FoxBin2Prg.exe v1.19.24)

Por: Fernando D. Bozzo

Está liberada la versión v2.4.18 de las herramientas Visual FoxPro 9 para PlasticSCM, con los siguientes cambios:

  • Algunos mensajes han sido convertidos al Inglés para permitir un uso Internacional más amplio
  • Actualizada la versión de FoxBin2Prg (solo el EXE) a la versión v1.19.24



Estas herramientas son un grupo de scripts vbs y programas Visual FoxPro 9 que se configuran dentro de PlasticSCM para poder invocar a FoxBin2Prg (incluye solo el EXE) desde dentro de la interfaz de Plastic.

El README.txt explica como se configura en Inglés y Español.

Nota: Los fuentes de FoxBin2Prg están en CodePlex, en el link indicado arriba en la versión.


Como actualizar las existentes:
Con descargarlas y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link de descarga:
https://github.com/fdbozzo/foxpro_plastic_diff_merge


Saludos!

Nueva versión v1.19.24 de FoxBin2Prg (Arreglos y mejoras)

Por: Fernando D. Bozzo

Está liberada la versión v1.19.24 de FoxBin2Prg con los siguientes cambios:

  • Bug Fix: La falta de AGAIN en algunos comandos USE provoca error de "tabla en uso" si se usa el PRG desde la ventana de comandos de VFP (Matt Slay). Este error afecta a quienes prefieren usar FoxBin2Prg desde la ventana de comandos de FoxPro con el comando DO y además quieren seguir teniendo el proyecto (PJX) abierto.
  • Bug Fix: Un campo de tabla llamado "text" que comienza la línea puede confundirse con la estructura TEXT/ENDTEXT y reconocer mal el resto del código (Mario Peschke). Para reconocer las estructuras TEXT/ENDTEXT dentro de FoxBin2Prg se analizan los inicios de línea que comiencen con la palabra TEXT. Pero en el caso de que haya por ejemplo un campo de un REPLACE o de un CREATE CURSOR que comience en una nueva línea, se llame "text" y además no tenga ningún simbolo de puntuación (como ","), entonces se producía un error de reconocimiento en el parser y todo el resto se asumía como un bloque TEXT/ENDTEXT. Afecta a los scx/vcx/sc2/vc2 que tengan un campo llamado "text" y en las condiciones antes descriptas.
  • Modificado el README.txt para que primero esté el texto en Inglés (Internacionalización). Como FoxBin2Prg está hospedado en VFPx que es de referencia Internacional y que contiene muchos proyectos Open Source para Visual FoxPro, por usabilidad.se sitúa la explicación en Inglés al inicio para que no confunda a los no Hispano-parlantes, y a continuación está en Español.
  • Bug Fix: El método GetTimeStamp genera un error cuando el dia o mes tiene solo 1 dígito. Este error se introdujo en la versión anterior (v1.19.23) donde se activó por defecto la generación de timestamps para los registros internos de los binarios, y ocurre cuando se regenera un binario que no tiene el timestamp en algún registro, en cuyo caso se regenera, y el día o el mes tienen 1 solo dígito. Afecta a los binarios indicados al regenerarlos y se soluciona volviendo a regenerar los que hallan fallado, usando esta versión.
  • Nuevo evento "run_aftercreate_db2" que permite ejecutar un programa externo cuando se usa FoxBin2Prg como objeto (por ejemplo, para exportar los datos). En la v1.19.19 se introdujo el evento "run_AfterCreateTable" para permitir ejecutar un programa externo, por ejemplo para importar los datos de una tabla si se habilita la conversión bidireccional para los DBFs. En esta ocasión es para lo opuesto, y así se completa la funcionalidad. Esta exportación e importación de datos se puede hacer usando FoxBin2Prg como objeto, y no se incluye dentro del programa para dar más flexibilidad en la implementación de esta característica y permitir que cada uno pueda implementarlo de la forma que mejor le sirva.
  • Nuevos tests unitarios para comprobar la nueva funcionalidad. Se han creado nuevos casos de prueba de FoxUnit para comprobar el fix del campo "text" y la correcta llamada de los eventos run_aftercreate_db2 y run_aftercreatetable.
  • Agregada la translación de los mensajes al alemán (Mario Peschke). Mi agradecimiento a Mario Peschke por haber hecho la traducción al Alemán de FoxBin2Prg (archivo foxbin2prg_de.h)


Como actualizar el FoxBin2Prg existente:
Con descargar el zip y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link  de descarga:
https://vfpx.codeplex.com/releases/view/116407


 Saludos!

jueves, junio 12, 2014

La importancia de un buen nombre para los procedimientos y las funciones


Por: Fernando D. Bozzo

Cuando se desarrollan nuevas funcionalidades, si queremos hacer las cosas bien lo haremos de forma encapsulada, usando control de errores, evitando en lo posible dependencias externas y parametrizando lo más posible, para intentar que haya claramente una entrada y una salida.

En este proceso, lo primero que elegimos y creamos es el nombre del procedimiento o función que contendrá el código con la implementación de la funcionalidad.

Lamentablemente a este paso muchas veces no se le da la importancia necesaria, siendo que de la claridad con la se defina esto, dependerá buena parte de la autodocumentación de la aplicación, y de que dentro de un tiempo nosotros u otros desarrolladores entendamos qué hacía o por qué.

En este artículo se verán algunos nombres que por su longitud a quienes estén acostumbrados a la vieja usanza les podrá resultar exagerado o demasiado verborrágico, pero es que los tiempos han cambiado y con los años se han aprendido nuevas lecciones por el camino.



Lo que importa es el nombre


Nombres como "procedimiento_1" o "proc_A" no indican absolutamente nada sobre su funcionamiento o intención, incluso algo más elaborado como "EvaluarHabilitaciones" puede ser ambiguo si no se usa correctamente.

Las buenas prácticas indican hacer métodos que hagan en lo posible una sola cosa y usar un nombre que sea lo más representativo posible de esa funcionalidad.

¿Pero qué regla se puede usar para evitar equivocaciones o nombres poco útiles y conseguir el mejor nombre?

Hay una regla muy fácil: Convertir el nombre del método que hemos elegido en una pregunta, y si las respuestas (los valores de salida) no son ambiguas y unívocamente responden a la pregunta, entonces ese es un buen nombre.



Veamos algunos ejemplos


1) Tenemos un método que debe devolver el estado de habilitación (enabled) de un grupo de controles de acuerdo a ciertas condiciones.


Rápidamente podríamos pensar algo como "EvaluarEstadosDeDeshabilitacion", ya que aparentemente este nombre está hablando sobre lo que hace internamente, lo cuál es cierto, y que se usará en una condición de este tipo:

IF EvaluarEstadosDeDeshabilitacion()
   * Asignar ENABLED=.T. a unos controles
ELSE
   * Asignar ENABLED=.F. a unos controles
ENDIF


Pero sometámoslo a la prueba de la pregunta a ver si es un nombre adecuado, y comparemos las respuestas:

Pregunta:
"¿Se van a Evaluar Estados de Deshabilitación?"

Respuestas posibles del método:
Verdadero
Falso

En este caso las respuestas confunden, porque ¿se van a evaluar o no esos estados?

Para complicarlo más, el nombre incluye una negación, "Deshabilitación", por lo que al responder afirmativamene, realmente estamos diciendo lo que no se debe hacer en vez de lo que sí se debe hacer. Como se ve, algo que debería ser sumamente sencillo comienza a complicarse sin sentido.

Pero dado que las respuestas del método realmente deben ser esas (Verdadero/Falso), debemos asumir entonces que las pregunta está mal hecha, y por consiguiente el nombre del método está mal.

Volvamos a pensarlo: La respuestas indican si se deben habilitar o no controles, ¿no sería mejor un nombre como "ControlesEvaluadosHabilitados" o "ControlesEvaluadosEnabled"?

Sometámoslo a la misma prueba:

Pregunta:
"¿Están los Controles Evaluados Habilitados?"

Respuestas posibles del método:
Verdadero
Falso

En este caso ambas respuestas definen precisamente los valores posibles a la pregunta, con lo que ese nombre es el adecuado. Luego, el ejemplo anterior quedaría así:

IF ControlesEvaluadosHabilitados()
   * Asignar ENABLED=.T. a unos controles
ELSE
   * Asignar ENABLED=.F. a unos controles
ENDIF



2) Tenemos un método que no debe devolver ninguna respuesta, sino solamente evaluar y actualizar los estados de habilitación antes comentados.


En este caso se trata de un método que invoca a otros métodos para realizar su tarea, por lo que aquí sí que "EvaluarEstadosDeHabilitacion" o "EavaluarYActualizarEstadosDeHabilitacion" sería un nombre correcto, ya que se usaría así:

PROCEDURE EvaluarYActualizarEstadosDeHabilitacion
   * Hacer las evaluaciones necesarias y configurar los ENABLED
ENDPROC

Pero sometámoslo a la prueba de la pregunta a ver si es un nombre adecuado, y comparemos las respuestas:

Pregunta:
"¿Se van a Evaluar Y Actualizar Estados de Habilitacion?"

Respuestas posibles del método:
Como no devuelve respuesta, se debe comparar con la veracidad de la intención, que en este caso es SI, se van a Evaluar Y Actualizar Estados de Habilitación.




3) Un nombre de método tomado de un sistema: "Formularios()". No devuelve nada, solo realiza una acción: Cierra los formularios abiertos.


¿Qué nos dice este nombre? Pues que tiene que ver con formularios, pero nada más.
¿Indica su función? No
¿Podemos deducir lo que hace? No

Entonces es un nombre inútil. Para la acción que realiza, un mejor nombre podía ser CerrarFormularios(), y no requería mucha imaginación ni trabajo extra.




4) Algunos ejemplos de nombres usados en casos de prueba automatizados con FoxUnit:


Deberia_Ejecutar_FOXBIN2PRG_ParaLaLibreria_FB2P_TEST_VCX_YValidarLosCamposDelRegistro

Deberia_Ejecutar_FOXBIN2PRG_ParaElForm__F_OptionGroup__YValidarLaVisualizacionDePantalla

Deberia_DevolverLaFechaHora_2013_12_01_08_02_00_ParaElValor_1132544064

Deberia_ObtenerLaUbicacionDelBloque_IF_ENDIF_CuandoCodigoCon_IF_ENDIF_predominante_esEvaluado


Creo que no necesitan ver el código ni los comentarios de estos métodos para saber lo que hacen, y eso es suficiente para demostrar el sentido de estos nombres extra-largos y cuán útiles son.




Resumen


Estas sugerencias de nomenclatura se basan en la forma de pensar natural sobre las cosas: cuando queremos un manzana de la frutería, vamos a ver si "HayManzanasEnLaFruteria", jamás iremos a ver si "NoHayManzanasEnLaFrutería", ya que la negación no es la forma natural de razonar, y por eso es que no es recomendable usar negaciones en los nombres de los métodos.

Respecto de los nombres largos, hay que hacerlos lo más descriptivos posibles, a tal punto que no requiera tener que inspeccionar el código para saber lo que hacen.

Finalmente, recuerden hacerse la pregunta con el nombre del método: Si las respuestas admitidas son ambiguas o no son del todo exactas, entonces el nombre no está bien elegido y conviene cambiarlo.

Todo esto ayudará enormemente a la autodocumentación de las aplicaciones y a que tanto ustedes como cualquier otro desarrollador puedan saber qué hacen los procedimientos o funciones solo leyendo sus nombres, lo que también facilitará el mantenimiento de la misma, aunque pase mucho tiempo.

Incluso si alguien nuevo debe familiarizarse con el código, estas buenas prácticas lo ayudarán a no perderse y ser productivo en menos tiempo.



Hasta la próxima!


sábado, junio 07, 2014

Nueva versión v2.4.17 de las herramientas Visual FoxPro 9 para PlasticSCM (Incluye FoxBin2Prg.exe v1.19.23)

Por: Fernando D. Bozzo

Está liberada la versión v2.4.17 de las herramientas Visual FoxPro 9 para PlasticSCM, con los siguientes cambios:

  • Agregado switch "nFlags" en los scripts vbs para Plastic, para poder mostrar un mensaje de finalización de proceso, muy útil cuando se procesan muchos archivos o cuando se procesan archivos pesados que tardan (activo por defecto)
  • Activado por defecto el mensaje de finalización de proceso en los scripts vbs para usar con el administrador de archivos de Windows
  • Actualizada la versión de FoxBin2Prg (solo el EXE) a la versión v1.19.23



Estas herramientas son un grupo de scripts vbs y programas Visual FoxPro 9 que se configuran dentro de PlasticSCM para poder invocar a FoxBin2Prg (incluye solo el EXE) desde dentro de la interfaz de Plastic.

El README.txt explica como se configura en Inglés y Español.

Nota: Los fuentes de FoxBin2Prg están en CodePlex, en el link indicado arriba en la versión.


Como actualizar las existentes:
Con descargarlas y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link de descarga:
https://github.com/fdbozzo/foxpro_plastic_diff_merge


Saludos!

Nueva versión v1.19.23 de FoxBin2Prg (Arreglos y mejoras)

Por: Fernando D. Bozzo

Está liberada la versión v1.19.23 de FoxBin2Prg con los siguientes cambios:

  • Mejora: Los valores de los campos timestamp y uniqueid vuelven a los binarios. En los tx2 es configurable con los flags NoTimestamps y ClearUniqueID. En la v1.19.7 se introdujo la posibilidad de vaciar los timestamps de los binarios y tx2 con el switch NoTimespamt, y en la v1.19.10 se introdujo el flag ClearUniqueID para hacer lo mismo con los UniqueID. Desde esta versión esos campos se dejan con valor en los binarios siempre y los switch solo afectarán a los textos tx2 generados desde los mismos. El motivo es evitar diferencias innecesarias en los binarios, ya que si, por ejemplo, un proyecto PJX tiene estos campos vacíos y se abre el proyecto (con MODIFY PROJECT), aunque no se toque nada y se cierre, FoxPro completa varios de estos campos automáticamente, lo que produce diferencias que luego salen en el control de código como binario modificado.
  • Mejora: Agregado valor de sccdata por defecto. Este es otro campo que se dejaba vacío, pero que al abrir ciertos componentes con MODIFY, aunque no se modifiquen, FoxPro les rellena este campo con el valor por defecto. Desde esta versión los binarios regenerados tendrán este campo relleno con el valor por defecto, así FoxPro no lo rellena por su cuenta y se evitan diferencias en los binarios por este motivo.
  • Bug Fix: Arreglo de evaluación de la fecha para incluir los archivos ??T (vct, frt, mnt, sct, lbt). En la v1.19.21 se introdujo una mejora en la regeneración de archivos, controlada por el switch OptimizeByFilestamp (activa por defecto en foxbin2prg.cfg), en la que se optimizaba su creación dependiendo del timestamp de los archivos TX2 y de los archivos ??X. El problema es que si se modifica, por ejemplo, el backcolor de un form y se guarda, el archivo actualizado es el memo (SCT) y no el SCX, por lo que el archivo SC2 no se regeneraba, pudiendo perderse el cambio si se regeneraba el binario desde el mismo. Ahora se compara también el timestamp de los archivos .??T (memo), para evitar este problema. Esto solo afecta las instalaciones que tengan OptimizeByFilestamp = 1 en foxbin2prg.cfg
  • Bug Fix: Agregada propiedad faltante "BorderColor" en props_optiongroup.txt. No hubo ningún reporte de error por esto, pero faltaba en la lista y fue agregada.
  • Bug Fix: Agregada props Stretch en props_image.txt (Kenny Vermassen). La ausencia de esta propiedad en la lista de propiedades provocaba en ciertas situaciones que algunas imágenes se redimensionen mal, dependiendo del valor de la propiedad Stretch y del tamaño de la imagen. Esto solo afecta a los forms o clases que usen imágenes más grandes que el tamaño asignado al height/width del control image que las contiene.
  • Bug Fix: Agregada props Enabled en props_image.txt. No hubo ningún reporte de error por esto, pero faltaba en la lista y fue agregada.


Como actualizar el FoxBin2Prg existente:
Con descargar el zip y reemplazar los archivos en el sitio que los hayan puesto antes es suficiente.


Link  de descarga:
https://vfpx.codeplex.com/releases/view/116407


 Saludos!