Programación 1º – UD4 – Documentación del código

¿Qué es documentar el código?

Documentar el código es como dejar notas o instrucciones dentro de tu programa para que tú (en el futuro) o cualquier otro programador pueda entender qué hace tu código y por qué lo hace. Es como poner etiquetas o carteles que expliquen los rincones de tu programa.

¿Quién leerá esta documentación?

Principalmente:

• Tú mismo (cuando vuelvas a ver el código en unos meses).
• Otros programadores que trabajen contigo o que tengan que modificar tu código.

¿Por qué es tan importante?

Porque ayuda a:

• Mantener el código (arreglar errores o mejorarlo).
• Reutilizarlo en otros programas.
• Entenderlo más rápido.

¿Qué cosas deberías documentar?

Mínimo deberías poner comentarios en:

• Las clases
• Los métodos
• Los atributos (variables dentro de una clase)
• Los constructores

Y también opcionalmente en:

• Bucles complicados
• Algoritmos que no sean obvios
• Cualquier cosa que no se entienda solo leyendo el código

¿Cómo se hace en Java?

Se usa una herramienta que ya viene con Java y se llama Javadoc.

Para que Javadoc funcione, usamos comentarios especiales que empiezan así:

/**
 * Aquí va la explicación
 */

Ese bloque sirve para documentar lo que viene justo debajo, como un método o una clase.

Ejemplo de un comentario con Javadoc:

/**
 * Calcula el área de un círculo dado su radio.
 *
 * @param radio El radio del círculo
 * @return El área calculada
 */
public double calcularArea(double radio) {
    return Math.PI * radio * radio;
}

¿Qué son las etiquetas @?

Son como palabras clave que le dicen a Javadoc qué información especial debe mostrar. Algunas muy comunes:

Orden recomendado de etiquetas

1. @author
2. @version
3. @param
4. @return
5. @exception o @throws
6. @see
7. @deprecated

Actividades de programación

Actividad 1: Documentar una clase de utilidades matemáticas

• Agrega comentarios Javadoc a la clase y a cada método.
• Usa @param, @return, @throws, @author.

public class Calculadora {

    public int sumar(int a, int b) {
        return a + b;
    }

    public int restar(int a, int b) {
        return a - b;
    }

    public int multiplicar(int a, int b) {
        return a * b;
    }

    public int dividir(int a, int b) {
        return a / b; // Cuidado: puede lanzar ArithmeticException si b es 0
    }
}

Actividad 2: Documentar constructor y atributos

• Documenta la clase, el constructor y los métodos get.
• Usa @param para el constructor, y @return para los getters.

public class Persona {
    private String nombre;
    private int edad;
    private String dni;

    public Persona(String nombre, int edad, String dni) {
        this.nombre = nombre;
        this.edad = edad;
        this.dni = dni;
    }

    public String getNombre() {
        return nombre;
    }

    public int getEdad() {
        return edad;
    }

    public String getDni() {
        return dni;
    }
}

Actividad 3: Usar @see para vincular clases

• Documenta ambas clases.
• Usa @see Persona en Estudiante, y viceversa.
• Puedes añadir un enlace externo con @see <a href="...">texto</a>.

public class Persona {
    // Código como el de la actividad anterior
}

public class Estudiante extends Persona {
    private String curso;

    public Estudiante(String nombre, int edad, String dni, String curso) {
        super(nombre, edad, dni);
        this.curso = curso;
    }

    public String getCurso() {
        return curso;
    }
}

Actividad 4: Marcar métodos obsoletos con @deprecated

• Documenta potenciaAntiguo con @deprecated.
• Usa {@link #potencia(double, double)} para indicar la nueva versión.

public class Calculadora {

    /**
     * Método antiguo para calcular potencias.
     */
    public int potenciaAntiguo(int base, int exponente) {
        int resultado = 1;
        for (int i = 0; i < exponente; i++) {
            resultado *= base;
        }
        return resultado;
    }

    public double potencia(double base, double exponente) {
        return Math.pow(base, exponente);
    }
}

Actividad 5: Generar documentación HTML con Javadoc

• Documenta esta clase usando Javadoc.
• Luego, en terminal, ejecuta: javadoc -d doc Vehiculo.java
• Abre el archivo doc/index.html con tu navegador para ver la documentación generada.

/**
 * Clase que representa un vehículo básico.
 */
public class Vehiculo {
    private String marca;
    private int velocidad;

    public Vehiculo(String marca) {
        this.marca = marca;
        this.velocidad = 0;
    }

    public void acelerar(int incremento) {
        velocidad += incremento;
    }

    public int getVelocidad() {
        return velocidad;
    }
}