decoratorejemplo

UD4. Optimización y documentación

1. Refactorización.
2. Patrones de diseño.
3. Control de versiones.
4. Documentación.

1 Refactorización.

Toda la información sobre refactorización la encontrarás en este enlace.

2 Patrones de diseño.

Toda la información sobre patrones de diseño la encontrarás en este enlace.

3 Control de versiones.

Un producto software se modifica infinitas veces durante su tiempo de vida y por lo tanto se necesita una herramienta que permita llevar un control de los distintos cambios que pueda sufrir a lo largo de su desarrollo o vida útil.

gitGIT es un SCV gratuito y de código abierto.
Se puede utilizar para proyectos pequeños y grandes.
Es fácil de aprender y tiene un buen rendimiento.

En la mayoría de productos software, muchas personas intervienen en su desarrollo y por lo tanto imprescindible que el control de versiones no se haga de forma manual puesto que se pueden cometer muchos errores y el coste sería muy alto.

3.1 ¿Cómo se almacenan las distintas versiones?

Los sistemas de control de versiones se pueden clasificar según cómo se almacena el código. Tenemos dos tipos de sistemas.

Sistemas Centralizados. Su gestión es mucho más sencilla como se puede deducir. El repositorio es único y en él se almacenará todo el código del software a guardar. Generalmente en muchos software se generan varias ramas y en ese caso, un responsable deberá aprobar el almacenamiento de las distintas ramas de software. En estos sistemas el control es mayor y generalmente existe un único número de versión lo que hace que su gestión sea más sencilla. Esa rigidez implica que muchas veces se desee tener algo más de flexibilidad y por tanto optar a otro tipo de configuración como los sistemas distribuidos.

Sistemas Distribuidos. En este tipo de sistemas, cada programador mantiene una copia del repositorio. Todos los usuarios tienen una copia del software. La ventaja es que en caso de fallo habrá muchas copias de las cuales se podrá recuperar la última versión. En el servidor principal residirá la copia principal.

Cuando se quiere trabajar con versiones inestables o versiones no oficiales, muchos desarrolladores y empresas de software optan por utilizar este tipo de sistemas. En el caso que una versión inestable o de prueba supere las pruebas pertinentes, el responsable las subirá al repositorio común y formará parte del proyecto.

Generalmente este tipo de versiones se realizan cuando se quieren mejorar ciertos módulos o se quieren incorporar nuevas funcionalidades al software. Además, la ventaja de que el usuario tenga una copia del proyecto en su propio equipo hace que el trabajo sea mucho más ágil. El servidor también está más descargado y no se necesitará una máquina tan potente.

3.2 Tipos de colaboración en un sistema de control de versiones

Generalmente se colabora de dos formas en un sistema de control de versiones (SCV). La primera y más sencilla es trabajar con el sistema en exclusiva. Muchas veces un usuario es responsable de una parte o módulo de un sistema o desarrollo software. Cuando lo está modificando notifica al repositorio que esa parte esta pendiente de modificación y el mismo repositorio bloquea esa parte para que no sea modificada. Cuando finaliza el trabajo lo comunica al repositorio y sube el software modificado. El repositorio desbloquea esa parte y queda disponible para los demás usuarios.

La otra forma que hay de trabajar en un SCV es trabajar de forma colaborativa. En este caso, cada usuario trabaja con su cuenta en su copia local y cuando termina los cambios que estaba realizando los sube al repositorio común. Los problemas más comunes al trabajar de esta forma es que pueden aparecer conflictos con las distintas modificaciones. La coordinación en este tipo de trabajo es fundamental para evitar dichos problemas.

La forma en la que se trabaja con un sistema de control de versiones se llama workflow o flujo de trabajo. Existen diferentes formas de trabajar con un SCV y por lo tanto diferentes tipos de flujo de trabajo. A continuación se comentarán los más frecuentes:
repositorio centralizado

SCV con flujo de trabajo centralizado

Flujo de trabajo centralizado o workflow centralizado. Es un sistema muy propio de la vieja escuela. Se suele utilizar un servidor centralizado y los desarrolladores van publicando sus actualizaciones de código en él. Estos sistemas funcionan de forma exclusiva, lo que implica que si alguien está modificando un elemento ningún otro desarrollador puede realizar actualizaciones del mismo.


repositorio común

Workflow con gestor de integración

Flujo de trabajo con gestor de integración. En ocasiones, para un mayor control sobre las versiones del proyecto se utiliza un gestor de integración que suele ser una persona del equipo de desarrollo que actualiza los trabajos en el repositorio común. Algo parecido a un guardia de tráfico. Los desarrolladores actualizan sus repositorios públicos y es el gestor de integración el encargado de actualizar el repositorio común con los trabajos públicos independientes de los desarrolladores. Este sistema suele ser muy utilizado en SCV distribuidos.

Workflow con tenientes y dictador

Workflow con tenientes y dictador

Flujo de trabajo con dictador y tenientes. Este tipo de flujo de trabajo se utiliza solamente en casos de proyectos masivos (como por ejemplo la evolución de un kernel de Linux). Es una evolución del modelo anterior. En proyectos muy grandes existen varias personas supervisoras de varias partes del proyecto llamadas tenientes y una persona llamada dictador que puede actualizar los cambios que sus tenientes le envían. En este sistema todos los desarrolladores tienen acceso al repositorio para poder clonarlo y crearse su propia copia del mismo.

4 Documentación.

Durante el proceso de elaboración de software se genera mucha, pero que mucha documentación. Yo como ingeniero de testing he leído muchos documentos de muchos programadores, analistas, jefes de proyecto, etc. Y lo que tengo claro es que es mejor no generar ningún tipo de documentación que generar documentación inservible o poco útil.

Durante el proyecto se genera mucha documentación pero también antes y después. La documentación de un programa o producto va dirigida a muchas personas como programadores, usuarios, personas que van a testear la aplicación, etc.

Lo más importante de la documentación como decía antes es que sea de calidad. Alguna de la documentación que se genera en proyectos informáticos en ocasiones carece de calidad. Se suele ver mucho en los manuales de usuario. Muchas veces, este tipo de manuales se encargan de describir obviedades de las ventanas o interfaces que cualquier usuario medio puede intuir delante del programa y omiten información importante que es de utilidad.

La mayoría de las veces esta falta de calidad viene dada porque el tiempo que se le dedica a la documentación es escaso. Y en ocasiones, a los programadores no nos gusta crear documentación y lo hacemos de mala gana y luego eso se traduce en un pésimo resultado.

Al final, si la documentación no tiene calidad nunca va a servir como referencia y no se le dará ningún uso.

4.1 ¿Cómo escribir documentación de calidad?.

A continuación se muestran ciertas pautas para escribir documentación de calidad:

  • Haz siempre esquemas antes de ponerte a escribir. Puedes también incorporar dichos esquemas a tus manuales.
  • Clasifica la información según importancia. Es mejor tener un buen documento principal y muchos anexos que un documento principal muy grande.
  • Realiza resúmenes, esquemas, documentos maestros etc. Siempre es bueno hacer un trabajo de síntesis en el que se explique el conjunto de la documentación.
  • Muchos lenguajes de programación, ellos mismos tienen sus propios estándares y herramientas de documentación. Si es así es mejor utilizarlos. Por ejemplo Java tiene Javadoc.
  • A la hora de escribir la documentación para el usuario hay que anticiparse y responder a las preguntas que se pueda hacer el usuario o lector. Habrá que responder a preguntas como: ¿y ahora después qué hago? ¿Qué hace este botón? ¿Qué implica borrar esto o aquello? etc.
  • Es importante la claridad a la hora de escribir documentación de usuario. Hay empresas de software a las que les gusta utilizar segunda persona (“tú”) en vez de tercera persona (“el usuario”). Yo particularmente prefiero la tercera persona pero antepongo a esto la claridad.
  • Hay que elegir bien la herramienta de documentación. En ciertos casos el obcecarse con herramientas como procesadores de textos hace difícil de seguir el hilo a la documentación de distintos programas y módulos, quizás sería mejor utilizar herramientas hipertextuales o herramientas que facilitan la documentación del código como HelpLogix, RoboHelp, Doc-To-Help, etc. No desechar herramientas colaborativas como wikis, google docs, y demás.
  • Muchas veces se generan dos documentos de usuario para el software. La guía de usuario y el manual de referencia. Un manual de referencia explica el software de una forma más en profundidad. En ocasiones, este manual de referencia se distribuye como ficheros de ayuda dentro de la propia aplicación. La guía de usuario es más sencilla y explica cómo realizar paso a paso ciertas tareas con el software. Suelen tener formato de tutorial.
  • Hay que tener en cuenta el nivel del usuario que va a leer la documentación. En estos documentos hay que dejar claro qué es lo que el usuario no debe ni puede hacer, las consecuencias de ejecutar algo, qué ocurre si no se hace algo, etc.
  • Realiza un checklist en el cual cualquier programador puede cumplimentarlo y ver si realmente está generando documentación de calidad para un proyecto. No te bases solamente en este artículo sino que tendrás que investigar más sobre la creación de documentación en proyectos software.

    4.2 Tipos de documentación.

    Cualquier tipo de software puede verse desde dos puntos de vista diferentes. Uno es el aspecto técnico (los componentes, clases, ficheros, interfaces, bases de datos, etc.) y otro es el aspecto funcional (cómo funciona el sistema, que acciones realizan cada uno de sus componentes, cómo se comunica con otro software, etc.).

    La documentación de un software debe cubrir tanto el aspecto técnico como el aspecto funcional del mismo. El aspecto técnico está más orientado a los desarrolladores y el funcional a los usuarios.

    Durante el ciclo de vida de un proyecto, la documentación es una tarea que se inicia con el mismo y termina también al final de él. De hecho, la documentación es un proceso que nunca termina.

    Veamos la importancia de la documentación en cada una de las fases del ciclo de vida clásico:

    Fase inicial. En esta fase se planifica el proyecto, se hacen estimaciones, se conviene si el proyecto es rentable o no, etc. Es decir, se establecen las bases de cómo se van a desarrollar el resto de fases del proyecto. En un símil con la construcción de un edificio sería el ver si se dispone de licencia de construcción, cuánto me va a costar el edificio, cuántos trabajadores voy a necesitar para construirlo, quién lo va a construir, etc. La fase de planificación y estimación es la más complejas de un proyecto. Para esto se necesita gente con experiencia tanto en la elaboración de proyectos como en las plataformas en las que se va a realizar el mismo. De esta fase surgen muchos documentos tanto de planificación (general y detallada) como documentos de estimaciones en el que se incluyen datos económicos, posibles soluciones al problema y sus costes, etc. Son documentos que se realizan a alto nivel y se acuerdan con la dirección de la empresa o las personas responsables del proyecto. En estas fases iniciales se suelen tomar decisiones que a veces afectan a todas las demás fases del proyecto, con lo cual tiene que estar todo bien documentado, detallado y soportado por datos concretos.

    Análisis. En esta fase se analiza el problema. Consiste en recopilar, examinar y formular los requisitos del cliente y analizar cualquier restricción que se pueda aplicar. Todas las entrevistas con el cliente por lo tanto tienen que estar registradas en documentos y generalmente esos documentos se consensuan con el cliente y desde mi punto de vista algunos tienen hasta caracter contractual. Yo, como jefe de desarrollo, en algunos proyectos he hecho firmar al cliente un documento de requisitos de la aplicación en el cual mi equipo se compromete a realizar las especificaciones indicadas por el cliente y también el cliente se compromete a no variar sus necesidades hasta por lo menos terminar una primera release. Como puedes ver, es un documento que obliga a ambas partes a cumplir con lo acordado y en muchas ocasiones establece un marco de relación entre cliente y desarrollador.

    Diseño. Esta fase consiste en determinar los requisitos generales de la arquitectura de la aplicación y dar una definición precisa de cada subconjunto de la aplicación. En esta fase los documentos ya son más técnicos. Se suelen crear dos documentos de diseño, uno más genérico en el que se tiene una visión de la aplicación más general y otro detallado en el que se profundizará en los detalles técnicos de cada módulo concreto del sistema. Estos documentos los realizarán los analistas junto con la supervisión del jefe de proyecto.

    Codificación o implementación. Esta fase consiste en la implementación del software en un lenguaje de programación para crear las funciones definidas durante la etapa de diseño. Durante esta fase se crea documentación muy detallada en el que se incluye código. Aunque mucho código se suele comentar en el mismo programa, también se tienen que generar documentos donde se indica por ejemplo para cada función las entradas, salidas, parámetros, propósito, módulos o librerías donde se encuentra, quién la ha realizado, cuándo, las revisiones que se han realizado de la misma, etc. Como puedes ver, el detalle es máximo teniendo en cuenta que ese código en un futuro va a tener que ser mantenido por la misma o seguramente otra persona y toda información que pueda recibir a veces es poca.

    Pruebas. En esta fase se realizarán pruebas para garantizar que la aplicación se programó de acuerdo con las especificaciones originales y los distintos programas de los que consta la aplicación están perfectamente integrados y preparados para la explotación. Como se ha visto anteriormente, las pruebas son de todo tipo. Yo clasificaría la documentación de las pruebas en dos bloques diferentes. Existen unas pruebas funcionales en las que se prueba que la aplicación hace lo que tiene que hacer con las funciones acordes a los documentos de especificaciones que se establecieron con el cliente, y esas pruebas se deberían realizar con el cliente delante. Mientras que se están realizando las pruebas se tienen que hacer todo tipo de anotaciones para luego plasmarlas en un documento en el que tendrá que darle el visto bueno el cliente (que por ese motivo estuvo en las pruebas). En ese documento se van detallando fallos tanto de la propia aplicación como modificaciones a la misma si no cumple con las especificaciones iniciales. En el caso que haya discrepancia se suele consultar documentación anterior para que no se incluyan en este punto funcionalidades nuevas o variaciones de las funcionalidades. En otro documento aparte se detallarán los resultados de las pruebas técnicas realizadas. A estas pruebas ya no hace falta que asista el usuario o cliente puesto que son de carácter meramente técnico. En estas pruebas se harán cargas reales, se someterá la aplicación y el sistema a estrés, etc.

    Explotación. En esta fase se instala el software en el entorno real de uso y se trabaja con él de forma cotidiana. Generalmente es la fase más larga y suelen surgir multitud de incidencias, nuevas necesidades, etc. Toda esta información se suele detallar en un documento en el que se documentan los errores o fallos detectados intentando ser lo más explícito posible puesto que luego los programadores y analistas deben de revisar estos fallos o bugs y darle la mejor solución posible. También surgirán otras necesidades que se van a ir detallando en un documento y que pasarán a realizarse en operaciones de mantenimiento.

    Mantenimiento. En esta fase se realizan todo tipo de procedimientos correctivos (corrección de fallos) y actualizaciones secundarias del software (mantenimiento continuo) que consistirán en adaptar y evolucionar las aplicaciones. Para realizar las labores de mantenimiento hay que tener siempre delante la documentación técnica de la aplicación. Sin una buena documentación de la aplicación, las labores de mantenimiento son muy difíciles y su garantía en ese caso sería escasa. Todas las operaciones de mantenimiento tienen que estar documentadas porque se tiene que conocer quién ha realizado la operación, qué ha hecho y cómo. También tienen que estar documentadas porque deberían probarse por otra persona distinta al programador.

    Como se puede observar, en cada una de las fases se generará al menos un documento. Ningún proyecto serio se desarrolla sin tener en cuenta la documentación de cada una de las fases correspondientes, sería un desastre sin lugar a dudas.

    Es importante que la documentación sea de calidad. Como anécdota decir que en un proyecto en el que estuve realizando el control de calidad del mismo un usuario dijo del documento de ayuda: “La ayuda no ayuda”. Esa frase que me hizo gracia en primer instancia nos hace reflexionar y pensar que

    Ninguna aplicación se debería entregar ni se desarrollar si no cuenta con los siguientes documentos:

    Manual de usuario. Es el documento de referencia que utilizará el usuario para desenvolverse con el programa. Deberá ser autoexplicativo y de ayuda para el usuario. Este manual debe de servirle al usuario para aprender cómo se maneja la aplicación y qué es lo que hay que hacer y lo que no. Si como técnico no vas a hacer un manual que le sirva al usuario en su comienzo o práctica diaria, es mejor no hacerlo o realizar otro tipo de documentación.

    Manual técnico. Es el manual dirigido a los técnicos (el manual para los mecánicos citado anteriormente). Con esta documentación, cualquier técnico que conozca el lenguaje con el que la aplicación ha sido creada debería de poder conocerla casi tan bien como el personal que la creó.

    Manual de instalación. En este manual se explican paso a paso los requisitos y cómo se instala y pone en funcionamiento la aplicación.

    Desde la experiencia, recalcar una vez más la importancia de la documentación, puesto que sin documentación una aplicación o programa es como un coche sin piezas de repuesto, cuando tenga un problema o haya que repararlo no se podrá hacer nada.

    4.3 Generación automática de documentación.

    Es importante tener el código comentado y la mejor de las opciones es comentar el código dentro del mismo. Otras opciones implican mantener documentos que la mayoría de las veces se quedan obsoletos y desactualizados.

    En Java, el código se documenta en el mismo fichero y con una herramienta llamada Javadoc se pueden extraer los textos y comentarios de dicho código fuente y transformarlos en páginas web con formato HTML.

    Los comentarios como saben los programadores de Java se insertan entre los caracteres /** y */.

    Además del comentario, se pueden incluir otras etiquetas más específicas como las siguientes:

  • @author. Como su nombre indica, identifica al autor del código fuente.
  • @version. Esta etiqueta identifica la versión del código.
  • @return. Especifica el valor de retorno de la función o método. No hay que especificar dicha etiqueta si la función devuelve un valor void.
  • @since. Esta etiqueta especifica la fecha de creación del programa.
  • @deprecated. Especifica que esta función, método o la misma clase está obsoleta.
  • @param <nombre_par>. Describe el parámetro “nombre_par”. Se suele especificar cada parámetro en una línea.
  • @see. Utiliza esta etiqueta si quieres redirigir al que lee el código a otro apartado del mismo.
  • @link <URL>. Utiliza esta etiqueta si quieres dirigir al usuario a una URL en concreto.
  • Veamos un ejemplo de documentación muy sencillo:

    package holamundoswing;

    /**
    * clase holamundoswing
    * @author Juan Carlos
    * @version 1.0
    * @since 06/06/2015
    *
    *

    Esta clase corresponde a un ejemplo de holamundo con swing.

    */

    //Debemos importar todos los componentes que vamos a utilizar en nuestra
    //aplicación
    import java.awt.FlowLayout;
    import java.awt.event.ActionEvent;
    import java.awt.event.ActionListener;
    ……

    Recuerda.
    Para generar la documentación de la clase anterior se ha ejecutado desde línea de comandos lo siguiente:
    javadoc holamundoswing.java

    Tras ejecutar javadoc, el cual se puede ejecutar desde el propio IDE (NetBeans o Eclipse) o desde línea de comandos (si utilizas Geany deberás ejecutarlo de esta manera), obtenemos una serie de páginas web con la documentación de la aplicación.

    javadoc_holamundoswing

    JavaHelp como herramienta para generación de ayudas. .

    Muchas veces es necesario o requerido que la propia aplicación tenga un menú de ayuda integrado dentro de la misma. JavaHelp es una extensión de Java que nos puede ayudar a implementarlo.

    Generará una serie de ventanas basadas en ficheros XML y HTML las cuales podrán ser mostradas al usuario para ayudarle a manejar la aplicación.

    Ejercicio propuesto.
    Investiga JavaHelp y añade al programa holamundoswing una ventana de ayuda.
    Resumen
    Nombre del artículo
    Optimización y documentación
    Autor
    Descripción
    El artículo trata sobre refactorización, patrones de diseño y documentación de proyectos

    Deja un comentario

    Tu dirección de correo electrónico no será publicada. Los campos necesarios están marcados *

    Puedes usar las siguientes etiquetas y atributos HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>