Documentación de código con Doxygen y Maven

Voluminous documentation is part of the problem, not part of the solution.

-- Tom DeMarco, software development consultant

Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.

-- Dick Brandon

La documentación de proyectos software siempre ha sido un tema controvertido. Aspectos como la estructura, enfoque, perspectiva, y metodología han generado decenas de tratados y "estándares" (como sinónimo de modelo, patrón o referencia) tan voluminosos como imprácticos e irrealistas. Sin embargo, ya comenté en "La falacia de la Ingeniería del Software" mi poca confianza en la aplicación realista de muchas metodologías y estándares que comparten entre sí la escasez de referencias reales profesionales.

Mi experiencia a la hora de documentar un proyecto para la cesión de  administración y mantenimiento a terceros me ha enseñado que la documentación sólo sirve si:

• está contínuamente actualizada y sincronizada con lo que documenta (el adverbio continuamente aquí, es clave)
• la documentación y lo documentado están mutuamente accesibles
• tiene estructura y formato ágil para la consulta

Por supuesto, creo que los aforismos "cuanta más documentación mejor" o "toda documentación que se haga es poca" son del todo erróneos. El objetivo es la calidad, y creo honestamente que la cantidad participa de forma inversamente proporcional en una ecuación de calidad.

En lo que a documentación de código se refiere, los objetivos anteriores se obtienen con creces con sistemas de generación de documentación automatica:

• La documentación está junto a lo documentado favoreciendo la contínua actualización
• Están mutuamente accesibles
• La estructura es la idónea para facilitar el acceso a la documentación precisa fácilmente ya que suelen generar HTML

En este aspecto, la mejor herramienta que he probado hasta ahora es, sin duda y con diferencia, Doxygen.

Doxygen es un generador de documentación gratuito para  C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C# y D. Su licencia es GPL y sus resultados son comparables (e incluso mejores en algunos aspectos) a documentadores comerciales.

Los desarrolladores de Java, que ya conocen Javadoc, cuya generación está perfectamente integrada con Maven, se preguntarán para qué diablos necesitarían otro documentador. Como se comenta en la segunda cita introductoria de este artículo, Javadoc está bien: es mejor que nada. Pero comparar Doxygen con Javadoc es equivalente a comparar maven con "make".

Las características más destacables, frente a Javadoc, desde mi punto de vista:

• Genera automáticamente diagramas de clase y colaboración. Opcionalmente, diagramas de dependencia, llamada, etc... 
• Permite incluir el código fuente resaltado en la propia documentación
• Formatos: HTML,CHM, PDF, XML, etc..

Doxygen es una utilidad basada en línea de comando, como Javadoc, con más 100 opciones configurables que permiten ajustar la documentación final. Aunque la mayoría de las opciones interesantes ya están configuradas por defecto, Doxygen cuenta con un frontal gŕafico (doxywizard) muy util para gestionar las opciones y los ficheros de configuración. Se instala fácilmente ("sudo apt-get install doxgen-gui", en *ubuntu) existiendo distribuciones en código fuente y binarios para Mac OS y Windows... y, he aquí lo mejor: existe un plugin para maven.

Usando Doxygen con Maven
De la misma forma que podemos automatizar la generación de documentación javadoc en nuestras construcciones con maven, podemos hacerlo con Doxygen. Para ello, tan sólo debemos seguir los siguientes pasos:

1. Instalar Doxygen y hacerlo disponible en el path (para *ubuntu esto es automático con la instalación)
2. Añadir el plugin a nuestro pom.xml. A continuación muestro las opciones de configuración que yo suelo usar

    ...
    
        
            
                com.soebes.maven.plugins.dmg
                doxygen-maven-plugin
                1.0.1
            
        
    
    ....
    
        
            
                com.soebes.maven.plugins.dmg
                doxygen-maven-plugin
                1.0.1
                
                    false
                    es.cestel.szarza.balteus
                    1.0
                    spanish
                    true
                    true
                    true
                    true
                    src/main
                    true
                
            
        
    
    ....

Recomiendo probar con las opciones de generación de diagramas. Especialmente los diagramas de colaboración pueden ser muy útiles para ciertos módulos de proyecto.


Referencias y más información:

• Doxygen
• Doxygen Maven Plugin