Hablemos de Javadoc (Nivel Dummy)

Hablemos de programación… Supongamos que te inicias en el ámbito laboral con Java o vas a trabajar en un equipo de desarrolladores o vas a tomar un proyecto que alguien más ha hecho.

Sin duda alguna, tratar de entender el código de alguien más pudiera ser complejo, de hecho, muchas veces he encontrado proyectos, que es más fácil hacer de cero, que intentar trabajar sobre el código existente.

Javadoc es una herramienta del lenguaje de programación Java para documentar código fuente. Es importante dedicar tiempo a esto porque la documentación hace más legible, mantenible y perdurable el código. En entornos de alta rotación del equipo que trabaja en los proyecto es casi una obligación. Así que vayamos a lo práctico.

Javadoc define una serie de convenciones que estandarizan el modo en que se documenta el código, de este modo, se logran cosas como que los IDEs de desarrollo usen esta información para generar ayudas, que la utilidad javadoc (un programa distribuido con la plataforma Java) arme documentación off-line en formato HTML, o simplemente como intradocumentación estándar para tu sitio de estudio o trabajo.

En este artículo veremos las primeras nociones para documentar Clases con lo básico (probablemente en algún artículo posterior les comente opciones de documentación adicionales para enriquecer nuestros sistemas.

En primer lugar, un comentario con Javadoc inicia con los caracteres /** y finalizan con */

Dentro podemos colocar etiquetas con la notación de annotations, es decir, precedidas de un símbolo @

Las etiquetas que podemos colocar y dónde las podemos colocar están en la documentación oficial, (<sarcasmo>aunque gracias al grandioso y esmerado trabajo de Oracle</sarcasmo> en la migración de la documentación de Java creada por Sun, es posible que encontremos muchos enlaces rotos), pero con el siguiente ejemplo, te muestro algunas opciones básicas para que puedas comenzar con una documentación útil.

Nota: Si usas Netbeans y quieres agilizar un poco la documentación con Javadoc puedes ir al menú “Tools” >> “Analyze Javadoc” y podrás generar automáticamente la documentación básica para un proyecto completo (no necesitas plugins).

package com.guzman6001.example;

import com.remote.guzman6001.utils;

/**
 * Aquí puedes agregar una descripción de la clase que estás desarrollando
 * puedes agregar código HTML como <b>Negritas</b> o las que quieras.
 *
 * @author Autor de la clase.
 */

public class JavadocExample {

/**
 * Aquí incluyes la descripción del método que vas a implementar.
 *
 * @author guzman6001
 * @param par1 Explico para que sirve el primer parámetro (opcional)
 * @param par2
 * @throws ExampleException Explicación opcional de la excepción.
 * @throws OtherException
 * @return Explica que retorna el método
 */

  public String saludo(String par1, String par2) throws ExampleException,OtherException {
    if (par1.equals(par2)){
        return ExampleException;
    }
    if (par2.isEmpty()){
         return OtherException;
    }
    return "Everything is ok!";
  }

Pareciera en el ejemplo que hay más documentación que código, pero con la buena costumbre y la ayuda de las herramientas, la documentación será algo tan natural como necesario.

🙂

 

Deja un comentario