Uno, dos... Probando, probando...

Hecho Número Uno: Muy pocos desarrolladores (si es que hay alguno...) disfrutan probando lo que han desarrollado (por no hablar de lo que han desarrollado otros): es una tarea poco agradecida, rutinaria y repetitiva. Hecho Número Dos: Los desarrolladores de software están capacitados para crear programas que se ocupen automáticamente de tareas repetitivas, rutinarias y poco agradecidas.

Parece que de aquí se puede sacar inmediatamente una conclusión clara: ¿por qué no automatizar la realización de las pruebas del software?. Seguramente eso es lo que pensaron los creadores de JUnit cuando se decidieron a desarrollar un framework para facilitar la realización de las llamadas Pruebas Unitarias. El concepto parece que tuvo éxito y hoy JUnit está acompañado en el mundo cel código abierto por productos similares que permiten automatizar las pruebas en diversos entornos que no sean Java: NUtit (.NET), CppUnit (C++), pyUnit (Python)... en lo que se conoce colectivamente como familia xUnit

Sobre el papel, el uso de estos frameworks parece estar lleno de ventajas. Sin embargo, no son pocos los inconvenientes que aparecen al intentar adoptar su uso. Uno de los primeros, si no el principal, consiste en convencer a la gente, tanto a la que va a usarla como a los que toman las decisiones y auditan el tiempo dedicado al desarrollo. Es difícil convencer a la gente de que dedicar tiempo a escribir código que prueba otro código no es una pérdida de tiempo, sino una inversión. Aún estando convencido, es necesario disciplinarse para dedicarle el tiempo necesario (algo de lo que pocos proyectos suelen disponer en abundancia). De hecho, he visto rechazar ofertas de proveedores que incluían una partida dedicada al desarrollo de las baterías de pruebas, para quedarse con la misma oferta sin las pruebas (un poco más barata, claro). Y ello a pesar de que casi todos conocemos y hemos padecido el caso de proyectos grandes en los que, cada vez que se modifica algo, hay que probar (manualmente) toda la funcionalidad de nuevo porque puede haberse "roto" algo. En definitiva, una pesadilla de mantenimiento que podría haberse paliado con una política de pruebas automáticas adecuada.

Por otro lado, el uso de estas herramientas no siempre es sencillo. La instalación y uso en Java + Eclipse es casi trivial. Sin embargo, no me he animado a probar CppUnit (entre otras cosas porque empleo eMbedded Visual C++, no un Visual Studio más standard) porque no he visto claras inicialmente las instrucciones de instalación (igual leyéndolas con más detenimiento...). No conozco el caso de NUnit (aunque apostaría porque no será complejo de usar), y recuerdo haber trasteado un poco hace años con un VBUnit para Visual Basic que se integraba bastante bien con su IDE. Finalmente, no he probado pyUnit, pero porque Python lo utilizo básicamente para scripts más o menos sencillos y prototipos rápidos: no le veo mucho sentido a integrar las pruebas en estos casos.

Una vez resuelta la instalación y manejo del framework adecuado al lenguaje escogido, viene la gran duda: ¿qué y cómo probar?. Sin ni siquiera entrar en lo verdaderamente problemático (accesos a bases de datos, interfaces de usuario...), la mayoría de los ejemplos que se encuentran en la literatura del tema son demasiado triviales y no ayudan a ver como puede aplicarse todo esto en un proyecto real. A su favor hay que decir que la editorial Pragmatic Bookshelf tiene un par de títulos (Pragmatic Unit Testing in Java with JUnit y Pragmatic Unit Testing in C# with NUnit) que intentan dar un enfoque práctico a la automatización de las pruebas. Aún así (al menos el de Java y JUnit), se quedan cortos en lo que a ejemplos reales se refiere, aunque presentan una serie de prácticas y guías bastante útiles.

En conclusión, hoy por hoy es un escollo el pretender automatizar las pruebas en mi entorno de desarrollo. Entiendo que es algo necesario, sino imprescindible (sobre todo en proyectos de buen tamaño), pero no dispongo del tiempo necesario para experimentar y probar el xUnit correspondiente en un proyecto real. Eso sí, espero poder hacerlo algún día (y ahora mismo se ven posibilidades en el horizonte...).

Esa Cosa Llamada Documentación Técnica

No recuerdo que, cuando estudiaba, nada me hablara nunca de la Documentación Técnica. De hecho, en el Proyecto Fin de Carrera (lo más parecido a un proyecto real que se hacía), recuerdo como entregables cosas como la Especificación de Requisitos, el Análisis, el Diseño, los Fuentes y el Manual de Usuario, pero nada de Documentación Técnica...

Fue al empezar a trabajar cuando me enteré de que, después de hacer un programa (en RPG), se esperaba de mí que creara (o modificara... que como programador nuevo uno no hacía muchos programas nuevos) un documento de Word explicando los detalles internos del programa (algo de pseudocódigo, descripción de las validaciones, diseño de pantallas, ejemplos de llamadas...). La creación y mantenimiento de este tipo de documentación rivalizaba con la Documentación de Usuario por el premio a la tarea menos deseada de todo el proceso de desarrollo.

Más o menos por esa misma época (quizá un año antes...), oí hablar en un cursillo de Java por primera vez de una herramienta que hacía algo muy curioso: javadoc. Que a partir del código fuente y una serie de comentarios especiales, se pudieran generar automáticamente una serie de documentos HTML describiendo la estructura y detalles de las Clases empleadas, con el mismo formato que la propia ayuda estándar de Java, parecía casi cosa de magia.

A la primera versión de la Documentación Técnica reconozco que le veo poca utilidad: no deja de ser un duplicado del código fuente en un formato más legible. Aún asumiendo que el RPG es un lenguaje poco legible (o menos legible que otros, que no se me enfade nadie...), lo que se logra con esta documentación no es nada que no pueda lograrse con unos comentarios apropiados en los fuentes. Si es por un problema de acceso a los fuentes (era más fácil acceder a los documentos Word que a los fuentes de un programa RPG), hubiera visto más práctico generar automáticamente un listado de texto de los fuentes RPG cada vez que se pone un programa en producción. En todo caso, el peor problema de este tipo de Documentación Técnica es el de mantener sincronizadas las versiones de los fuentes y los documentos. Tarde o temprano, un documento se va a quedar desactualizado y examinarlo no va a servir de nada y no va a haber más remedio que acabar acudiendo a los fuentes.

Más útil es la segunda versión comentada de la Documentación Técnica, generada automáticamente. Quizá no lo sea tanto para uso interno, pero sí en entornos más "compartimentalizados" en los que se proporcionen componentes o librerías a otros grupos de desarrollo (o, evidentemente, si se desarrolla ese tipo de software para el usuario final). Así, nuestros clientes pueden usar nuestros componentes con el apoyo de una buena ayuda, y sin necesidad de acceso a nuestros fuentes: una situación idealmente perfecta.

Las ventajas de este tipo de documentación son principalmente dos. La primera es que se apoya en la que debería ser la principal fuente de documentación y resolución de dudas para el desarrollador: los comentarios del propio código fuente. Puede parecer una perogrullada, pero vale la pena repetirlo y destacarlo: la mejor Documentación Técnica es el código fuente (comentado adecuadamente). Evidentemente, esto obliga a desarrollar una disciplina a la hora de programar y comentar. Esto debería tenerse ya, pero la necesidad de crear unos comentarios que deban ser "compilados" por un sistema automático lo que logra es reforzar la necesidad de esa disciplina. Por duro que se haga comentar el enésimo método de acceso a una propiedad (El método getDato sirve para obtener el valor del dato...), vale la pena hacer el esfuerzo y acostumbrarse a dejar todo documentado: se gana en claridad y en tranquilidad. Si algo no está documentado ya no cabe la duda de si se debe a que es muy trivial o se trata de un olvido: ya no existe nada trivial.

El segundo punto a favor de estos métodos automáticos de documentar es, precisamente, que son automáticos. La generación de documentación se convierte así en un paso más del proceso de desarrollo, como el compilar para generar un ejecutable. ¿Qué inconvenientes se le puede poner a un sistema que automatiza la realización de una tarea que se considera desagradable? Ahora mismo no se me ocurre ninguna...

En resumen, la generación automática de Documentación Técnica permite generar fácilmente uno de los entregables que se le exigen al desarrollador, con el efecto secundario de reforzar la disciplina a la hora de comentar el código fuente. Todo son ventajas.

Así, aunque no se programe en Java, vale la pena buscar algún sistema similar a javadoc, por no hablar que la mayoría de lenguajes y entornos "modernos" (de Python a .NET) ya incluyen este tipo de herramientas. Y si no, es posible que existan de manera independiente. Ahora mismo trabajo en un proyecto desarrollado en Visual C++ (eMbedded) y empleo DoxyS para generar periódicamente la documentación de unas 200 Clases con un total de alrededor de 100.000 líneas de código. Es un programa sencillo (seguro que los hay más configurables y flexibles) para la sintaxis que requiere es muy poco intrusiva y lo que produce es más que suficiente para mis necesidades. Para hacer frente a algunas de sus carencias más problemáticas he programado unos scripts en Python para "preparar" los fuentes antes de llamar a la generación de la documentación. El resultado final es que, tras unos 20 minutos de procesamiento, se dispone de la Documentación Técnica de mi proyecto en un servidor web. La documentación es totalmente navegable, buscable, y va desde gráficos de llamadas de más alto nivel hasta la posibilidad de consultar el código fuente de un método concreto. Y todo eso sin más que ejecutar una sentencia en la línea de comandos: ¿qué más se le puede pedir?

Documentación de Usuario

Empecé a trabajar como miembro de una Horda Mongola en la época del Efecto 2000 y la adaptación al Euro. Muy pronto a alguien se le ocurrió que era un buen momento para establecer un nuevo sistema de documentación del software de la empresa, y fui el elegido gracias a que era el que más HTML sabía en el grupo. Se podría decir que diseñé un procedimiento y una metodología de trabajo por la que todos los programas que se hacían o modificaban se documentaban en forma de página HTML que, además de servir como el típico manual de usuario, incluía una pequeña simulación del proceso del programa (nada espectacular: sólo una sucesión de "pantallazos" estáticos con enlaces para pasar de uno a otro). Dado que estábamos hablando de software desarrollado en RPG III o RPG IV, hay que reconocer que la documentación resultaba bastante más vistosa que los propios programas. Sin embargo, fue entonces cuando descubrí, una vez acabada la excitación y el interés provocado al tener que elaborar todo el sistema, que realizar la documentación de usuario era un rollo. (Supongo que unos cuantos de mis compañeros también lo descubrieron, aunque quiero pensar que al menos la experiencia les sirvió para aprender algo de HTML básico, así que espero que no me guarden rencor por la parte que me toca). Incluso habíamos gente que nos dedicábamos íntegramente a documentar los programas creados por programadores más experimentados que no interesaba que "perdieran el tiempo" documentando. De ahí a que el documentar fuera casi considerado un castigo, sólo iba un paso...

Encuentro comprensible que a nadie (o casi nadie: no se puede generalizar) le guste la elaboración de la documentación de usuario. A los que nos dedicamos a esto del desarrollo de software nos gusta crear cosas que hagan algo. Tener que explicar luego en un documento de texto como utilizar nuestro software, con múltiples ilustraciones capturando todas y cada una de las pantallas del proceso (eso si no hay que retocarlas para que no muestren datos inapropiados), y listando obviedades varias (el botón de "Añadir Producto", sorprendentemente, ¡añade un producto!), es casi una tortura que resulta casi más costosa que el desarrollo de la aplicación en sí.

---

Un inciso necesario a raiz del último párrafo: la documentación de usuario debe ser exageradamente detallada, aún a riesgo de acabar creando un documento para tontos. Muchas cosas que el desarrollador considera obvias (y que lo son...), no las verá de la misma forma el usuario, así que vale la pena explicarlo todo hasta el más ínfimo detalle. Así, reduciremos las consultas de los usuarios o, por lo menos, no les daremos la excusa de que "en el manual no lo explica"

---

Por otra parte, en los propios procesos de las empresas es normal que haya previsto un tiempo insuficiente para el desarrollo de esta documentación (si es que hay previsto alguno). En el entorno de trabajo habitual, cuando un desarrollador finaliza un programa lo normal es que tenga unos cuantos esperando en cola y, una vez más, ni a él le interesar perder el tiempo en la desagradable tarea de documentar, ni a sus superiores les interesa que pierda el tiempo en vez de estar resolviendo problemas o creando nuevas funcionalidades que exigen los usuarios. Por supuesto, asumo que no se dispone de una persona dedicada exclusivamente a la redacción de documentación de usuario (Incluso si se dispone de personal especializado en la formación al usuario, la documentación se la debe proporcionar normalmente el propio desarrollador).

La consecuencia de todo esto es inmediata: montones de programas no disponen de sistemas de ayuda o manuales de usuario. O, lo que es peor todavía, disponen de ellos pero están obsoletos. Y esto hace que los usuarios ni se molesten en consultar la ayuda o los manuales: resulta mucho más efectivo llamar al departamento de Informática y consultar con el desarrollador.

Este es un problema con difícil solución, pues precisa que el desarrollador se conciencie de la necesidad de elaborar (y, más importante aún, mantener) la documentación de usuario y, por otra parte, precisa que los jefes de proyecto y similares tengan en cuenta que el manual de usuario es un entregable como otro cualquiera, y al que se le debe dedicar el tiempo necesario. Conseguir esto es donde está la principal dificultad, y aquí incluyo algunas de las razones por las que creo que es conveniente tener una buena documentación de usuario.

• Herramienta de Ventas. El manual de usuario es una buena forma de vender el software que describe, de manera que el potencial cliente se haga una idea de lo que es capaz de realizar sin necesidad de proporcionarle acceso (Aunque, obviamente, nunca va a ser tan bueno como una demo). Cuando se trata de presentar ofertas y similares, se vuelve imprescindible (además de ser una manera fácil de añadir peso a la oferta...). De hecho, no es raro que a la hora de presentar una oferta a clientes, el jefe de proyecto o de departamento se dé cuenta de la utilidad de disponer de una documentación de usuario extensa y completa.
  
• Reducción del Ruido Telefónico. Los que nos pasamos buena parte del día dando soporte a usuarios de nuestro software (o de software del que somos "responsables"), deberíanos arrepentirnos cada vez que suena el teléfono por no haber desarrollado un buen sistema de ayuda. Si los usuarios (o, si se dispone de ellos, el personal de soporte al usuario) tuvieran acceso a documentación que les permitiera resolver sus dudas y problemas por sí mismos, no llamarían tanto (o incluso, por utópico que suene, no llamarían nunca). De todas maneras, una vez el usuario ya no tiene confianza en la documentación y se acostumbra a resolver sus dudas por teléfono, el problema tiene mala solución...
  
• Recapitulación. La elaboración de la documentación de usuario tras un desarrollo o una modificación puede servir para asegurarnos de que el programa hace lo que debe, como debe, y como se pidió. No debería ser ese el momento, claro, pero el necesario repaso de las funcionalidades puede servir para descubrir lapsus y otros errores pendientes.
  

Reconozco que me cuesta encontrar más razones para justificar la necesidad de realizar la documentación de usuario (además de las obvias): supongo que no soy capaz de no verla como un "mal necesario". Es algo que hay que hacer, puedo racionalizar su necesidad, pero eso no hace que me guste...

Otro día hablaremos de la documentación técnica...

Toma de Requerimientos

Empezaremos por explicar el origen e intenciones de este blog.

Todo nace de la lectura de un libro: The Passionate Programmer, una recomendable mezcla de libro técnico (sección "prácticas y metodologías") y libro de auto-ayuda (sin rollos místicos). Aunque algunas cosas son probablemente poco aplicables a la situación de la industria en España (lógico: el libro es estadounidense), sigue siendo un texto más que interesante.

Varios de los consejos del libro en cuestión se refieren a llevar un blog en el que anotar las propias experiencias (relacionadas con el desarrollo de software, claro está), aunque sólo sea como cuaderno de bitácora para consulta propia. Y ese es el principal objetivo de este blog: servir ejercicio y herramienta de reflexión del que esto escribe. Si además alguien encuentra algo interesante o útil, bienvenido sea, pero el blog no pretende ser referencia de nada.

Y eso lleva a una necesaria presentación del autor. El que esto escribe lleva más de 10 años trabajando en el desarrollo de software en una empresa de servicios, integrado en el departamento de informática de dicha compañía. A pesar de ser un departamento relativamente grande, las circunstancias han hecho que haya desarrollado casi siempre mi trabajo de forma independiente, como un equipo de una sola persona, y habitualmente en entornos de desarrollo situados en los límites de lo considerado "corporativo". Es decir, por ejemplo, que mientras el software de la empresa se desarrollaba en RPG, yo me dedicaba a hacer programas en Visual Basic o C++.

En consecuencia, mis experiencias (como las de cualquiera) han marcado mis puntos de vista sobre como se funciona en el mundo real del desarrollo de software (y como se debería funcionar...). Esos puntos de vista son los míos, los de nadie más, y no pretenden sentar cátedra de ninguna manera: uno no es un gurú de nada. Si alguien los encuentra equivocados, probablemente tenga razón: la subjetividad es lo que tiene.

Dicho todo esto, uno de los ejercicios propuestos por el libro mencionado al principio de este post era hacer una lista con unos 10 temas sobre los que escribir y dedicar cada día una entrada a uno de dichos temas. No tengo aún hecha la lista (aunque un par de temas ya me rondan por la cabeza), y este mes de Enero promete ser intenso, así que no pienso comprometerme a seguir esas instrucciones al pie de la letra. Eso sí, espero que el blog cuente con alguna entrada más antes de que llegue Febrero.

Por supuesto, el nombre del blog procede de la genial serie británica The IT Crowd y es lo más parecido al "Hello, IT" de Roy que he podido encontrar libre.