Escritura de documentación para proyectos Java: de la A a la Z

Entrenador de Python en Línea para Principiantes

Aprende Python fácilmente sin sobrecargarte de teoría. Resuelve tareas prácticas con verificación automática, recibe pistas y escribe código directamente en el navegador, sin instalar nada.

Start Course

Introducción: Por qué la documentación es clave para un proyecto Java exitoso

La documentación de calidad no es solo una formalidad, sino una inversión en el futuro de su proyecto. Para un desarrollador Java, saber escribir documentación clara y estructurada es tan importante como conocer la sintaxis del lenguaje. Sin ella, incluso el código más elegante se convierte en una «caja negra» para otros desarrolladores, y el mantenimiento del proyecto se vuelve una pesadilla. En este artículo, analizaremos el ciclo completo de creación de documentación para un proyecto Java, desde los comentarios en el código hasta la publicación de un sitio web listo.

Veremos tres niveles principales de documentación: comentarios técnicos en el código (Javadoc), descripción de la arquitectura y la API (Markdown/AsciiDoc) y guías para usuarios. Aprenderá cómo, con las herramientas integradas de Java y formatos modernos, hacer que la documentación sea útil y legible.

Nivel 1: Documentación del código con Javadoc

Javadoc es la herramienta estándar de Java para generar documentación a partir de comentarios especiales. Analiza su código fuente y crea páginas HTML que describen clases, métodos y campos. El uso correcto de Javadoc es la base de la documentación técnica de cualquier proyecto Java.

Etiquetas principales de Javadoc

Para documentar la API pública (métodos/clases public y protected), utilice las siguientes etiquetas:

@param — descripción del parámetro del método.
@return — descripción del valor devuelto.
@throws o @exception — descripción de las excepciones que puede lanzar el método.
@see — enlace a otra clase o método.
@since — versión desde la que existe el elemento.
@deprecated — marca de elemento obsoleto con indicación de la alternativa.

Ejemplo: Documentación de una clase y un método

Veamos un ejemplo de una clase Calculator correctamente documentada:

/** * Calculadora simple para realizar operaciones aritméticas básicas. * * <p>Esta clase proporciona métodos para sumar, restar, * multiplicar y dividir dos números. Todos los métodos trabajan con el tipo {@code double}.</p> * * @author Iván Petrov * @version 1.0 * @since 2023-10-01 */public class Calculator {

    /**     * Suma dos números.     *     * @param a primer sumando     * @param b segundo sumando     * @return suma de a y b     */    public double add(double a, double b) {        return a + b;    }

    /**     * Divide un número entre otro.     *     * @param dividend dividendo     * @param divisor  divisor     * @return resultado de la división     * @throws ArithmeticException si divisor es igual a cero     */    public double divide(double dividend, double divisor) {        if (divisor == 0) {            throw new ArithmeticException("No se permite la división por cero");        }        return dividend / divisor;    }}

Después de ejecutar el comando javadoc -d doc src/Calculator.java obtendrá documentación HTML, donde cada etiqueta se transformará en un formato legible.

Consejos de estilo para Javadoc

Escriba los comentarios en español si el equipo del proyecto habla este idioma. Para proyectos Open Source, use inglés.
No duplique lo obvio. En lugar de @return the name, es mejor escribir @return nombre completo del usuario, incluyendo el apellido.
Use etiquetas HTML dentro de la descripción (por ejemplo, <code>, <ul>) para dar formato.

Nivel 2: Documentación arquitectónica y de API (Markdown / AsciiDoc)

Javadoc es excelente para describir clases individuales, pero para describir la arquitectura del proyecto, la interacción de los módulos y los principios generales de funcionamiento, se necesitan herramientas más flexibles. Aquí es donde entran Markdown y AsciiDoc.