Inicio > Informática e Internet > La subestimada javadoc

La subestimada javadoc

"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.

Anuncios
  1. Julio
    14 marzo, 2008 en 11:07

    Tenes toda la razón!!! Que sentido tiene que nos prohíban utilizar herramientas como esta, al contrario debería ser obligatorio entregar documentación de este tipo.

  2. Freygil
    21 noviembre, 2010 en 03:02

    Tienes toda la razón, nos olvidamos de esta súper herramienta, espero q después de leer tu articulo cambie algunas formas de pensar a cerca del javadoc.

    Tengo el rol de documentador y no logro fomentarlo, a pesar de mis constantes recordatorios del javadoc.

    • 21 noviembre, 2010 en 18:04

      Me alegra que un documentador haya confirmado que esto funciona. Gracias por el comentario ;-)

  3. 5 febrero, 2013 en 01:13

    Beautiful stuff post!

  4. 23 mayo, 2013 en 14:07

    Cool blog! Is your theme custom made or did you download it
    from somewhere? A design like yours with a few simple tweeks would really make my blog jump
    out. Please let me know where you got your theme. Kudos

  5. 1 junio, 2013 en 01:33

    My brother recommended I may like this blog. He used to be totally right.

    This submit actually made my day. You can not consider simply how
    much time I had spent for this information! Thank you!

  6. 2 junio, 2013 en 16:23

    Amazing blog! Do you have any tips for aspiring writers?

    I’m hoping to start my own site soon but I’m a
    little lost on everything. Would you recommend starting with a free
    platform like WordPress or go for a paid option? There are so many choices out there that I’m totally confused .. Any tips? Thank you!

  7. 21 junio, 2013 en 11:40

    Hey just wanted to give you a brief heads up and let you know a few of the pictures aren’t loading properly. I’m
    not sure why but I think its a linking issue. I’ve tried it in two different internet browsers and both show the same outcome.

  8. 2 julio, 2013 en 16:39

    Undeniably believe that which you said. Your favorite reason seemed
    to be on the net the easiest thing to be aware of. I say to you,
    I certainly get annoyed while people consider worries that they plainly don’t know about. You managed to hit the nail upon the top as well as defined out the whole thing without having side-effects , people can take a signal. Will likely be back to get more. Thanks

  9. 9 julio, 2013 en 02:15

    Write more, thats all I have to say. Literally, it seems as though you relied on the video to make your
    point. You definitely know what youre talking about,
    why throw away your intelligence on just posting videos to your weblog when
    you could be giving us something informative to read?

  1. 18 septiembre, 2014 en 04:46
  2. 19 septiembre, 2015 en 22:38

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: