Una de las partes más importantes de la programación y en la que seguramente muchas veces nadie piensa es la documentación. Dejar el código bien documentado y comentado es una tarea igualmente importante y que en nuestra trayectoria laboral nos será de gran utilidad.
La manera más conocida de documentar el lenguaje Java es JavaDoc. Se trata de una utilidad de Oracle que permite documentar clases de Java.
En primer lugar, lo más común es usar comentarios. Los comentarios se pueden escribir de tres maneras:
//Comentario en una línea simple
/*
*Comentario en más de una línea
*/
/**
*Comentario con JavaDoc
*/La estructura utilizada en JavaDoc es muy similar a la que se utiliza normalmente para comentarios, pero en la API se añade un asterisco extra al empezar, que es el característico para definirlo.
La gran peculiaridad de esta API es que permite añadir tags HTML dentro de los comentarios. Eso es debido a que JavaDoc, a través de los comentarios, genera un documento que servirá como documentación del proyecto.
Los comentarios para documentar, normalmente, se pueden poner en el código, encima de cualquier clase, en los métodos o atributos que queramos documentar.
Cuando se añadan comentarios, es necesario tener en cuenta que se debe describir cuál es la función de lo que se comenta. Por ejemplo, si comentamos una clase, haremos una breve explicación de lo que se encarga.
/**
* Aquí pondremos un resumen de la finalidad de esta clase
* Ej: Clase para documentar el funcionamiento de JavaDoc
*
* @author David Bermúdez
*
*/
public class JavaDoc {
/**
* Atributo nombre de la clase javaDoc
*/
private String nombre;
/**
* <p>Ejemplo de Javadoc con tags html.
* <a href="http://ciclo.iesnervion.es">IES Nervión</a>
* </p>
* @param ejemplo String que pasamos por parametro
* @return String con el resultado del metodo
* @see <a href="http://iesdavid.github.io">Teoría y ejemplos</a>
* @since 1.0
*/
public String ejemploMetodoJavadoc(String ejemplo) {
// Comentario con explicación de lo que se realiza en el método
return “OK”;
}
}