Nunca viene mal resfrescar la memoria, y bueno, ya que muchas veces nos olvidamos de cosas tan sencillas como documentar adecuadamente las aplicaciones que programamos. Cuando la aplicación empieza a ser considerablemente grande o cuando estamos trabajando varias personas en el proyecto es indispensable tener el codigo bien documentado. Es una tarea bastante tediosa, pero es una inversión de futuro, ya que nos permitirá ahorrar un montón de tiempo que al final se traduce en dinero.Para ello con java se utiliza la herramienta Javadoc, que viene incluida en cualquiera de los SDK de Java. En mi opinión el exceso de comentario es tan perjudicial como la falta de éstos, por lo que hay que seguir una máxima cuando estemos documentando: "Keep it Simple".
Los comentarios tratados por Javadoc son los que empiezan por /* o /**, nunca los que empiezan por //, por lo tanto usad esto para explicar algo dentro del codigo para cuando alguien esté buceando en el código pero no quereis que sea incluido en el Javadoc. De todas formas como ya he indicado lo mejor es comentar cuanto menos posible, si está bien escrito y deja claro lo que hace no hacen falta más explicaciones de como funciona. Aqui un resumencito sacado de los comandos:
- @param (clases, interfaces, métodos y constructores)
- @return (métodos)
- @throws(métodos, originalmente era @exception)
- @author (clases e interfaces)
- @version (clases e interfaces, es recomendado ponerlo)
- @see (clases,métodos e interfaces, en caso de que tenga relación con otra)
- @since (clases,paquetes e interfaces, indica que version de Java tenía cuando se añadió)
- @serial (para clases serializadas, os podeis olvidar)
- @deprecated (clases e interfaces, indica que la clase ha sido reemplazada y que por ello vamos a usar la nueva en vez de ésta. Debe indicar la versión de Java cuando fué reemplazada y poner la clase que la reemplaza.)
Primeramente debemos insertar estas líneas antes de la declaración de la clase
/**
* Explicación de qué es y para que sirve la clase
*
* @author tu_nombre
* @version numero_de_tu_version
*
* @param parametros
*
Podemos tambien añadir el resto de tags que hemos definido anteriormente.
Cosas a tener en cuenta:
- escribe en los métodos y clases claramente para que sirve la clase, como funciona y por que se implementa, aunque el método sea muy sencillo (ej: un setter).
- en caso de escribir una etiqueta @throws no expliques mucho, sólo cuando salta. Si son esperables, resuelvelo.
- usa el atributo {@link} cuando useis un deprecated para referenciar a la clase que le ha reemplazado. Por ejemplo:
@deprecated As of JDK 1.1, replaced by
{@link #setBounds(int,int,int,int)} - podeis meter etiquetas html en los comentarios javadoc.
La 
Entradas
