javadoc con UML

Hurgando por ahí me he encontrado con UMLGraph, una herramienta que genera gráficos UML a partir de unos textos que los describen. Lo bueno es que, al menos para el diagrama de clases, el texto que describe el diagrama UML es exactamente igual que un fuente java. Dicho de otra forma, si ponemos en el fichero "class UnaClase extends UnPadre {}", obtendremos un diagrama con una cajita UnaClase que hereda (flechita con triángulo) de una cajita UnPadre. Puedes ver el ejemplo aquí. Esto lo hace ideal para generar los gráficos UML de clases a partir de código fuente ya hecho.

Otro punto interesante es que viene con la posibilidad de invocar javadoc usando UMLGraph, de forma que en nuestro javadoc se generaría diagramas de clases incrustados. UMLGraph viene con un doclet que se puede usar desde el comando javadoc de java y de esta forma, javadoc generará la documentación de la forma habitual, pero incluyendo un gráfico de UML. En la descripción de un package, pondrá todas las clase incluidas en ese package y las relaciones entre ellas. En la descripción de una clase pondrá un dibujo de dicha clase con las relaciones (herencias, dependencias, etc) con otras clases del paquete o de otros paquetes. En la figura puedes ver un ejemplo de javadoc generado con el doclet de UMLGraph.

javadoc con grafico UML

Un detalle a tener en cuenta es que para que UMLGraph pueda generar los ficheros gráficos es necesario tener instalado previamente GraphViz.

En el diagrama de clases podrían configurarse muchas cosas, poner notas asociadas a las clases, poner otro tipo de cajas que no sean de clases, métodos que deben o no mostrarse, etc. La pega de ello es que iría configurado en código a base de anotaciones, por lo que el código quedaría algo "guarreado" para luego ver el dibujo bonito.

También pueden hacerse diagramas de secuencia, pero desgraciadamente la sintaxis del fichero de texto que lo describe ya no es java, así que no deja de ser una forma alternativa de hacer el diagrama. Puede ser interesante, por ejemplo, si guardamos los diagramas de secuencia en un sistema de control de versiones (como subversion). Siempre ocupa menos y es más interesante para ver diferencias con versiones anteriores un fichero de texto que no un gráfico o un proyecto entero de alguna herramienta compleja de generación de gráficos UML (Together, Rational,…).

Y otra cosa que a mí siempre me viene bien, es que UMLGraph está subido al repositorio ibiblio de maven y tiene plugin para el mismo. De esta forma, configurando el fichero pom.xml de nuestro proyecto maven (en concreto, configurando el plugin de javadoc para que use el doclet de UMLGraph), podemos generar el javadoc con gráficos UML directamente desde maven. La configuración sería algo parecido a esto

<reporting>
   <plugins>
      <plugin>
         <artifactId>maven-javadoc-plugin</artifactId>
         <configuration>
            <source>1.5</source>
            <aggregate>true</aggregate>
            <doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
            <docletArtifact>
               <groupId>gr.spinellis</groupId>
               <artifactId>UmlGraph</artifactId>
               <version>4.6</version>
             </docletArtifact>
             <additionalparam>
                    -inferrel -inferdep -quiet -hide java.*
                    -collpackages java.util.* -qualify
                    -postfixpackage -nodefontsize 9
                   -nodefontpackagesize 7
             </additionalparam>
          </configuration>
       </plugin>
    </plugins>
</reporting>

Con esto, un simple mvn javadoc:javadoc nos generaría la documentación javadoc de nuestro proyecto maven, gráficos UML incluidos.

 

Problemillas con StarUML

En ocasiones y para hacer diagramas UML rápidamente, usamos StarUML. Es una aplicación gratuita y sencilla para hacer diagramas UML rápidamente. Sin embargo, tiene una serie de problemas que nos han traido de cabeza hasta que hemos descubierto los motivos y hemos podido evitarlos.

El problema principal es con el idioma español de Windows y los puntos/comas decimales de los números. La herramienta no entiende la coma decimal de español y da los siguientes problemas:

  • No permite hacer ingeniería inversa. Si se intenta, empieza a dar errores con estos temas.
  • No permite el "layout" automático de los diagramas (que automáticamente recoloque las figuras para que queden más ordenadas).

Buscando por internet, encontramos un LocaleFix.bat. Si arrancamos StarUML con este bat, supuestamente se corrigen estos problemas. Sin embargo, usarlo trae otros problemas.

  • Al abrir con LocaleFix.bat, es posible que algunas etiquetas de los diagramas de secuencia (y otras) se descoloquen, quedando un poco más arriba o abajo de lo normal.
  • Si volvemos a poner en su posición esas etiquetas descolocadas, es posible que la siguiente vez que abramos el proyecto esas etiquetas no sean visibles (siguen estando las flechas, pero no los textos). En esta situación, si intentamos exportar el gráfico a un fichero jpg nos dará un error y no lo hará.

Al final, la solución, es andar con mucho cuidado:

  • Abrir StarUML sin usar el LocalFix.bat para el trabajo normal.
  • Abrir StarUML con LocaleFix.bat si queremos hacer una ingeniería inversa, pero sólo para eso y sin tocar nada más. Una vez hecha la ingeniería inversa, se salva el proyecto y se rearranca StarUML sin LocaleFix.bat

 

ArgoUML, StarUML y Netbeans

En su momento estuve mirando plugins de UML para eclipse, pero ninguno me convenció, hacían demasiado lento eclipse o eran demasiado cutres. Así que me he decidido a buscarlas por separado, independientes.

Por supuesto, tenemos Together -que creo que ahora va con JBuilder-, y Rational, pero son muy, muy caras.

Como gratuitas, he probado ArgoUML, que es sencilla de instalar y tiene ingeniería inversa. Sin embargo, me da problemas en cuanto hago una ingeniería inversa de un centenar de clases. Supongo que es cuestión de investigar cómo arrancarla con más memoria. Tampoco me ha parecido demasiado intuitiva. Quizás sea porque las herramientas UML con las que he trabajado suelen tener otra organización de las cosas.

Me ha gustado más StarUML, se parece más a las que estoy acostumbrado y es nativa, pero tiene un pequeño problema con las comas y los puntos -cosas del idioma-. Se arregla con un LocaleFix.bat que alguien ha hecho. Al final y de momento, creo que esta es la herramienta gratuita por la que me decido.

También probé Netbeans, que en su versión 6.0 viene con UML -creo que está en beta-, mientras que se puede añadir dicho UML a la actual estable, la 5.5.1. Me ha  sorprendido gratamente, no sólo el UML, sino el entorno en sí. Hace años trabajé con él y lo dejé para pasarme a eclipse. Veo ahora que netbeans ha mejorado bastante. En cuanto al UML de netbeans, parece bastante más robusto y potente que el StarUML o el ArgoUML, pero hay una cosa que no me ha gustado. Pone los diagramas demasiado bonitos, con muchos colorines. Supongo que es configurable.

Lo que sí tengo que pensar, ahora que he visto netbeans, es si le doy otra oportunidad. Quizás me cambie de entorno uno o dos meses para comparar con eclipse.