Testing Colombia

Testing con calidad

Herramientas

Doxygen para Java!

Las tareas de documentación de código por lo general suelen ser muy tediosas, como tal el mayor porcentaje de tiempo de los proyectos de desarrollo en cualquier ámbito es dedicado a la codificación, siendo la documentación del mismo muy pobre y en ocasiones no se hace, esto sin duda es una muy mala práctica, debido a que un código que no se documenta a la larga puede llegar a ser inutilizable o simplemente se puede caer en re-trabajos. Hoy en día existen mejores prácticas que indican dentro de los proyectos siempre estimar dentro de las tareas de los proyectos tiempo prudente para la realización de la documentación y también su revisión, para ello comentare una herramienta que facilita las labores de documentación de código como lo es “Doxigen” la cual es muy sencillo de usar y está disponible para los sistemas operativos:

  • Windows
  • Linux
  • Mac os

también para diferentes lenguajes de programación los cuales se pueden ver directamente Aqui en su web, para este ejercicio será enfocado en java.

Para este ejemplo tengo un proyecto en java muy sencillo el cual es solo ilustrativo y no pretende demostrar lógicas, como tal es solo para enfocarse en la documentación del código allí contenido, para la instalación de la herramienta está documentado en la Web de la herramienta, con lo cual me centrare en el ejemplo práctico sobre un proyecto java.

Este proyecto tiene una clase “Consultas_Vehiculo.java” la cual contiene los siguientes métodos:

Metodo1 Metodo2 Metodo3

La forma más elegante de definir en Doxigen un bloque de documentación es así:

/**

* esto es un ejemplo

*/

Lo cual se antepone a la función, método o la clase que se quiera documentar

En esta documentación se usa la siguiente sintaxis que es la que propone Java doc y es interpretada por Doxigen:

@author como se muestra en el primer ejemplo, hace referencia a la persona que crea la clase, pero también puede usarse para quien haga cambios a futuro sobre la misma en diversas partes de una clase o también quien implemente nuevos métodos.

@Brief Sirve para hacer una descripción detallada de lo que se desea documentar, la palabra Brief no es obligatoria, como se aprecia en los ejemplos anteriores.

@Param Se usa para describir las variables o parámetros que se usan en la clase y también en los métodos o funciones, se debe especificar el nombre de la variable.

@Return Para el caso de los métodos especifica cual es el resultado que retornara una ves sea ejecutado

@note permite añadir una nota adicional para resaltar algo o documentar algo muy específico.

@see Permite realizar una referencia hacia un método u otra clase del proyecto que tenga relación con lo que se esta documentando.

Configuración:

Una vez instalada la herramienta, la configuración de la misma es muy sencilla, se deben parametrizar las siguientes opciones:

El primer paso es en la vista “Wizard” definir donde la herramienta generara la documentación, para esto basta indicar cualquier folder dentro del sistema.

Se requiere especificar unos parámetros como (Nombre del proyecto, sinopsis, versión, logo), estos como tal sirven para darle mejor presentación al formato de la documentación, un parámetro importante es la ruta del proyecto (Source Code directory), aquí se debe elegir la raíz del proyecto, pensando en que se quiera una documentación completa y también pensando en que algunas funcionalidades de la herramienta van a depender de esta selección.

En el menú de la izquierda hay otra serie de opciones para definir el formato de la documentación y demás, pero como tal para el ejemplo se dejó por default, eligiendo el formato de salida HTML.

Dox1

El paso siguiente es la vista “Expert”, esta vista tiene un gran número de parámetros para configurar, pero en realidad la configuración por default ya aprovecha bastante las capacidades de la herramienta, en esta configuración en el menú “Source Browser” se cambió el parámetro “Source Browser” a activo, esto se verá más adelante para que sirve.

Dox2

El último paso en la vista Run se puede revisar el resumen de la configuración final y por ende hacer la ejecución y poder apreciar el resultado final.

Dox3

Esta es una vista de la presentación de la documentación del proyecto de ejemplo:

Presentacion

Como se puede apreciar se generó un menú en la sección de la izquierda el cual por clases va generando sub-secciones con los métodos, además de esto se puede ver de manera organizada y ágil la documentación que está contenida en la clase “Vehículo”, como por ejemplo la documentación del primer método:

Metodo_1

También se puede acceder al código de la clase completo para consulta sin necesidad de abrir el proyecto.

Metodo_2

Mejores Prácticas:

  • Documentar todo el código en lo posible, evitando caer en perdida de agilidad.
  • Buscar documentar en forma clara y que sea entendible para otras personas.
  • Documentar las actualizaciones especificando fecha y autor.
  • Mantener un orden en la estructura de las clases evitando declarar atributos y objetos por todas partes.
  • Para entornos donde se tenga configurado integración continua se puede validar al hacer nuevos cambios que se necesite documentar siempre que se generen cambios en el código.
  • Evitar comentarios obvios
  • Evitar dejar la documentacion del codigo para el final.
  • las metodologias agiles recomiendan documentar lo estrictamente necesario.
  • Evitar mantener bloques de código comentados que no se usan, esto solo muestra inseguridad, se puede hacer mientras etapas de pruebas de los cambios, pero retirarlos del código productivo.
  • Mantener nombres de métodos, variables, clases y en fin todos los objetos bajo una nomenclatura relacionada y clara. ¡Evitar ser muy gracioso!!!
  • La ultima y no menos importante, “Por el código se conoce al desarrollador”.

Si tienes comentarios o mas informacion que aportar para mejorar el articulo no dudes en comentar.

2 Comentarios

  1. Myriam Maldonado

    Necesitamos de carácter un ingeniero con conocimientos de Doxygen, para que pueda hacer unos cambios y mostrar cierta información. Sólo se necesita por
    1-2 horas, hasta obtener el resultado deseado.

    Ustedes nos pueden ayudar?

Deja un comentario

Tema creado por Anders Norén