Archivo

Archive for 13 marzo 2008

La subestimada javadoc

13 marzo, 2008 12 comentarios

"javadoc" es una herramienta que viene integrada con el JDK. Es un ejecutable, como "javac" (el compilador) y también se especifican las clases que se quieren "compilar". Lo diferente con javadoc es que no genera código ejecutable (bytecode en el caso de Java), sino documentos html.

Personalmente veo a javadoc como otra gran bondad de ese lenguaje sobrehumano que es Java. Aligera una de las tareas que supongo que la mayoría de los programadores considera un estorbo: La documentación.

¿Cómo funciona javadoc? Es muy sencillo. A medida que se codifica una clase se colocan comentarios delimitados por "/**" y "*/" para indicar inicio y fin del comentario respectivamente. En medio puede ir cualquier cantidad de texto con los caracteres que se desee. Dichos comentarios se colocan justo sobre la declaración de atributos y métodos públicos. Los comentarios colocados sobre métodos y atributos privados son ignorados por defecto, porque de todas formas dado el principio de abstracción del paradigma de programación orientada a objetos no tiene sentido saber para qué sirven si no son accesibles.

El ejecutable javadoc parsea los archivos de las clases y organiza los documentos html. En caso de haber herencia, incluye también los comentarios de los métodos y atributos heredados. También dispone de etiquetas y palabras especiales para ayudar a especificar mejor ciertas cosas como los parámetros de un método.

Aquí hay algunos screenshots de la salida que genera javadoc:

 

Se ve familiar, ¿no? ¡Claro!, Sun Microsystems, de hecho quienes se merecen el mérito de Java incluyendo javadoc, utilizan javadoc para crear la documentación técnica del JDK disponible en línea o para descargar de forma gratuita.

En dos años de entregar proyectos con su respectiva documentación, la documentación técnica generada con javadoc sólo ha sido válida una vez. ¿Por qué no aprovechar semejante herramienta? Sirve para los propósitos de documentación técnica, y bastante bien. La presentación de la información es bastante organizada. Y lo mejor, no se tiene que dedicar tiempo específicamente a la documentación, porque se puede hacer directamente mientras se programa. Esto significa que se tiene mucho más fresco qué se está haciendo, para qué sirve lo que se está creando y se puede explicar mejor. En resumen, documentación técnica de muy buena calidad que no toma tiempo extra hacer. Es una lástima que debido a la relativamente mala aceptación que tiene, los programadores no la usemos y a veces ni siquiera se conozca su existencia.