Optimización y Documentación

1// ✗ ANTES: Un método enorme que hace demasiadas cosas
2public double procesarPedido(String nombreCliente, String producto,
3                             int cantidad, double precioUnitario,
4                             boolean esClienteVIP, boolean hayStock) {
5    // Validar datos
6    if (nombreCliente == null || nombreCliente.isEmpty()) {
7        throw new IllegalArgumentException("Nombre requerido");
8    }
9    if (cantidad <= 0) {
10        throw new IllegalArgumentException("Cantidad debe ser positiva");
11    }
12    if (!hayStock) {
13        throw new IllegalStateException("Sin stock");
14    }
15
16    // Calcular precio
17    double subtotal = cantidad * precioUnitario;
18    double descuento = 0;
19    if (esClienteVIP) {
20        descuento = subtotal * 0.15;  // ← número mágico
21    }
22    double precioConDescuento = subtotal - descuento;
23    double iva = precioConDescuento * 0.21;  // ← número mágico
24    double total = precioConDescuento + iva;
25
26    // Registrar pedido (código repetido en otros métodos)
27    System.out.println("Pedido registrado: " + nombreCliente);
28    System.out.println("Producto: " + producto + " x" + cantidad);
29    System.out.println("Total: " + total + " €");
30
31    return total;
32}

1// ✓ DESPUÉS: Código organizado, legible y reutilizable
2
3public class GestorPedidos {
4
5    private static final double DESCUENTO_VIP    = 0.15;
6    private static final double PORCENTAJE_IVA   = 0.21;
7
8    // Método principal: ahora se lee como una narración
9    public double procesarPedido(Pedido pedido) {
10        validarPedido(pedido);
11        double total = calcularTotal(pedido);
12        registrarPedido(pedido, total);
13        return total;
14    }
15
16    // Cada método tiene una sola responsabilidad
17    private void validarPedido(Pedido pedido) {
18        if (pedido.getNombreCliente() == null || pedido.getNombreCliente().isEmpty()) {
19            throw new IllegalArgumentException("Nombre del cliente requerido");
20        }
21        if (pedido.getCantidad() <= 0) {
22            throw new IllegalArgumentException("La cantidad debe ser positiva");
23        }
24        if (!pedido.hayStock()) {
25            throw new IllegalStateException("Producto sin stock disponible");
26        }
27    }
28
29    private double calcularTotal(Pedido pedido) {
30        double subtotal       = pedido.getCantidad() * pedido.getPrecioUnitario();
31        double descuento      = calcularDescuento(subtotal, pedido.isClienteVIP());
32        double baseImponible  = subtotal - descuento;
33        double iva            = baseImponible * PORCENTAJE_IVA;
34        return baseImponible + iva;
35    }
36
37    private double calcularDescuento(double subtotal, boolean esVIP) {
38        return esVIP ? subtotal * DESCUENTO_VIP : 0.0;
39    }
40
41    private void registrarPedido(Pedido pedido, double total) {
42        System.out.println("Pedido registrado: " + pedido.getNombreCliente());
43        System.out.println("Producto: " + pedido.getProducto()
44                         + " x" + pedido.getCantidad());
45        System.out.printf("Total: %.2f €%n", total);
46    }
47}

1<?xml version="1.0"?>
2<!DOCTYPE module PUBLIC
3    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
4    "https://checkstyle.org/dtds/configuration_1_3.dtd">
5
6<module name="Checker">
7    <!-- Longitud máxima de línea: 120 caracteres -->
8    <module name="LineLength">
9        <property name="max" value="120"/>
10    </module>
11
12    <module name="TreeWalker">
13        <!-- Nombres de clases: UpperCamelCase -->
14        <module name="TypeName"/>
15
16        <!-- Nombres de métodos y variables: lowerCamelCase -->
17        <module name="MethodName"/>
18        <module name="LocalVariableName"/>
19
20        <!-- Constantes: UPPER_SNAKE_CASE -->
21        <module name="ConstantName"/>
22
23        <!-- Llaves siempre en la misma línea -->
24        <module name="LeftCurly"/>
25        <module name="RightCurly"/>
26
27        <!-- Espacios alrededor de operadores -->
28        <module name="WhitespaceAround"/>
29
30        <!-- Javadoc obligatorio en métodos públicos -->
31        <module name="JavadocMethod">
32            <property name="scope" value="public"/>
33        </module>
34
35        <!-- Detectar importaciones sin usar -->
36        <module name="UnusedImports"/>
37    </module>
38</module>

1// ✗ PMD: "Unused variable 'resultado'" — variable declarada pero no usada
2public void calcular() {
3    int resultado = operacion();  // nunca se usa
4    System.out.println("Hecho");
5}
6
7// ✗ PMD: "Empty catch block" — excepción silenciada
8try {
9    archivo.close();
10} catch (IOException e) {
11    // nada — el error desaparece sin dejar rastro
12}
13
14// ✗ PMD: "Unnecessary return" — el return es redundante
15public void imprimir(String texto) {
16    System.out.println(texto);
17    return;  // innecesario al final de un método void
18}
19
20// ✗ PMD: "Avoid using 'System.out.println'" en código de producción
21// usar un Logger en su lugar
22
23// ✓ Versiones corregidas:
24public void calcular() {
25    int resultado = operacion();
26    System.out.println("Resultado: " + resultado);
27}
28
29try {
30    archivo.close();
31} catch (IOException e) {
32    logger.error("Error al cerrar el archivo: " + e.getMessage());
33}
34
35public void imprimir(String texto) {
36    System.out.println(texto);
37    // sin return innecesario
38}

1// ✗ SpotBugs: "Equals method compares class names" — comparación incorrecta de Strings
2String nombre = obtenerNombre();
3if (nombre == "Juan") {      // == compara referencias, no contenido
4    System.out.println("Es Juan");
5}
6// ✓ Correcto:
7if ("Juan".equals(nombre)) { // equals() compara contenido
8    System.out.println("Es Juan");
9}
10
11// ✗ SpotBugs: "Resource not closed" — conexión que puede no cerrarse si hay excepción
12Connection conn = dataSource.getConnection();
13Statement stmt = conn.createStatement();
14ResultSet rs = stmt.executeQuery(sql);
15// si la siguiente línea lanza excepción, conn nunca se cierra → fuga de recursos
16procesarResultados(rs);
17conn.close();
18
19// ✓ Correcto: try-with-resources garantiza el cierre
20try (Connection conn    = dataSource.getConnection();
21     Statement stmt     = conn.createStatement();
22     ResultSet rs       = stmt.executeQuery(sql)) {
23    procesarResultados(rs);
24} // conn, stmt y rs se cierran automáticamente al salir del bloque
25
26// ✗ SpotBugs: "Null pointer dereference" — posible NullPointerException
27String resultado = obtenerResultado(); // puede devolver null
28int longitud = resultado.length();     // NullPointerException si resultado es null
29
30// ✓ Correcto:
31String resultado = obtenerResultado();
32if (resultado != null) {
33    int longitud = resultado.length();
34}

1# ── Configuración inicial (una sola vez) ─────────────────────────────
2git config --global user.name  "Tu Nombre"
3git config --global user.email "tu@email.com"
4
5# ── Inicializar un repositorio nuevo ─────────────────────────────────
6git init                    # crea un repositorio en el directorio actual
7git clone URL               # descarga un repositorio existente
8
9# ── Ver el estado actual ──────────────────────────────────────────────
10git status                  # qué archivos han cambiado
11git diff                    # qué cambios exactos hay en los archivos modificados
12git log --oneline           # historial de commits en una línea cada uno
13git log --oneline --graph   # historial con visualización de ramas
14
15# ── Registrar cambios ─────────────────────────────────────────────────
16git add NombreArchivo.java  # preparar un archivo concreto
17git add .                   # preparar TODOS los cambios del directorio
18git commit -m "feat: añadir validación de edad en formulario de registro"
19
20# ── Sincronizar con el repositorio remoto ────────────────────────────
21git push origin main        # subir commits locales al servidor
22git pull origin main        # descargar y fusionar cambios del servidor
23git fetch origin            # descargar cambios del servidor sin fusionar
24
25# ── Deshacer cambios ─────────────────────────────────────────────────
26git restore NombreArchivo.java  # descartar cambios del directorio de trabajo
27git restore --staged Nombre.java # quitar del área de preparación (sin perder cambios)
28git revert HEAD             # crear un nuevo commit que deshace el último

1# Crear una nueva rama y situarse en ella
2git switch -c feature/login-con-google
3# equivalente al clásico: git checkout -b feature/login-con-google
4
5# Ver todas las ramas
6git branch          # locales
7git branch -a       # locales y remotas
8
9# Cambiar entre ramas
10git switch main
11git switch feature/login-con-google
12
13# Fusionar una rama en la actual (estando en main)
14git switch main
15git merge feature/login-con-google
16
17# Subir la rama al repositorio remoto
18git push origin feature/login-con-google
19
20# Eliminar la rama local una vez fusionada
21git branch -d feature/login-con-google

1tipo(ámbito): descripción breve en imperativo
2
3[cuerpo opcional: explicación más detallada del cambio y la razón]
4
5[pie opcional: referencias a issues, breaking changes]
6
7─────────────────────────────────────────────────────────────────────
8Tipos más comunes:
9  feat:     nueva funcionalidad
10  fix:      corrección de error
11  docs:     cambios solo en documentación
12  style:    formato (sin cambio de lógica)
13  refactor: refactorización (sin nueva función ni corrección)
14  test:     añadir o corregir pruebas
15  chore:    tareas de mantenimiento (build, dependencias)
16
17─────────────────────────────────────────────────────────────────────
18Ejemplos de buenos mensajes:
19
20✓ feat(auth): añadir inicio de sesión con Google OAuth2
21✓ fix(pedidos): corregir cálculo de IVA en pedidos con descuento
22✓ refactor(cliente): extraer validación de email a método propio
23✓ test(inventario): añadir pruebas para el caso de stock agotado
24
25✗ arreglos
26✗ cambios
27✗ actualizaciones del código
28✗ cosas varias
29✗ wip

1# 1. Crear el repositorio en GitHub (desde la web, sin inicializarlo)
2
3# 2. En tu terminal, desde el directorio del proyecto:
4git init
5git add .
6git commit -m "feat: commit inicial del proyecto"
7
8# 3. Conectar con el repositorio remoto
9git remote add origin https://github.com/usuario/mi-proyecto.git
10
11# 4. Subir el código
12git push -u origin main
13# El flag -u establece origin/main como la rama remota por defecto
14# En los push siguientes basta con: git push
15
16# 5. Verificar la conexión
17git remote -v

1/**
2 * Gestiona el inventario de productos de la tienda.
3 *
4 * <p>Esta clase proporciona operaciones de consulta, actualización y
5 * auditoría del stock disponible. Todas las operaciones son atómicas
6 * y seguras para uso en entornos concurrentes.</p>
7 *
8 * <p>Ejemplo de uso básico:</p>
9 * <pre>{@code
10 * GestorInventario gestor = new GestorInventario(dataSource);
11 * boolean disponible = gestor.hayStock("REF-001", 5);
12 * if (disponible) {
13 *     gestor.reducirStock("REF-001", 5);
14 * }
15 * }</pre>
16 *
17 * @author Rodrigo Cabello
18 * @version 1.3.0
19 * @since 1.0
20 * @see Producto
21 * @see PedidoService
22 */
23public class GestorInventario {
24
25    /**
26     * Comprueba si hay suficiente stock de un producto.
27     *
28     * <p>La comprobación incluye stock reservado por otros pedidos
29     * en proceso. Para conocer el stock bruto sin reservas,
30     * usar {@link #getStockTotal(String)}.</p>
31     *
32     * @param referencia La referencia única del producto a comprobar.
33     *                   No puede ser {@code null} ni estar vacía.
34     * @param cantidadNecesaria El número de unidades requeridas.
35     *                          Debe ser un valor positivo mayor que cero.
36     * @return {@code true} si hay stock disponible para la cantidad solicitada;
37     *         {@code false} en caso contrario.
38     * @throws IllegalArgumentException si {@code referencia} es {@code null}
39     *         o vacía, o si {@code cantidadNecesaria} es menor o igual a cero.
40     * @throws ProductoNotFoundException si la referencia no existe en el catálogo.
41     */
42    public boolean hayStock(String referencia, int cantidadNecesaria) {
43        if (referencia == null || referencia.isBlank()) {
44            throw new IllegalArgumentException("La referencia no puede ser nula ni vacía");
45        }
46        if (cantidadNecesaria <= 0) {
47            throw new IllegalArgumentException(
48                "La cantidad necesaria debe ser positiva, se recibió: " + cantidadNecesaria);
49        }
50        int stockDisponible = repositorio.getStockDisponible(referencia);
51        return stockDisponible >= cantidadNecesaria;
52    }
53
54    /**
55     * Reduce el stock de un producto tras confirmar un pedido.
56     *
57     * @param referencia      La referencia del producto.
58     * @param cantidadVendida El número de unidades vendidas.
59     * @throws IllegalArgumentException   si los parámetros no son válidos.
60     * @throws StockInsuficienteException si el stock disponible es menor
61     *                                   que la cantidad a reducir.
62     * @deprecated Usar {@link #reducirStockConAuditoria(String, int, String)}
63     *             para registrar el motivo de la reducción. Este método
64     *             se eliminará en la versión 2.0.
65     */
66    @Deprecated(since = "1.2", forRemoval = true)
67    public void reducirStock(String referencia, int cantidadVendida) {
68        reducirStockConAuditoria(referencia, cantidadVendida, "Sin motivo registrado");
69    }
70}

1# Con la herramienta javadoc directamente
2javadoc -d docs/api -sourcepath src/main/java -subpackages com.miempresa
3
4# Con Maven (genera en target/site/apidocs/)
5mvn javadoc:javadoc
6
7# Con Maven, incluyendo los tests
8mvn javadoc:test-javadoc
9
10# Ver la documentación generada
11# Abrir target/site/apidocs/index.html en el navegador

1name: CI — Integración Continua
2
3# El pipeline se ejecuta en cada push y en cada pull request a main
4on:
5  push:
6    branches: [ main, develop ]
7  pull_request:
8    branches: [ main ]
9
10jobs:
11  build-y-pruebas:
12    runs-on: ubuntu-latest     # servidor con Ubuntu donde se ejecutará
13
14    steps:
15      # 1. Descargar el código
16      - name: Checkout del repositorio
17        uses: actions/checkout@v4
18
19      # 2. Configurar Java 17
20      - name: Configurar Java 17
21        uses: actions/setup-java@v4
22        with:
23          java-version: '17'
24          distribution: 'temurin'
25
26      # 3. Caché de dependencias Maven (acelera ejecuciones posteriores)
27      - name: Caché de dependencias Maven
28        uses: actions/cache@v4
29        with:
30          path: ~/.m2
31          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
32
33      # 4. Compilar el proyecto
34      - name: Compilar
35        run: mvn compile --no-transfer-progress
36
37      # 5. Ejecutar pruebas unitarias
38      - name: Pruebas unitarias
39        run: mvn test --no-transfer-progress
40
41      # 6. Análisis de código estático
42      - name: Checkstyle
43        run: mvn checkstyle:check --no-transfer-progress
44
45      # 7. Empaquetar (solo en la rama main)
46      - name: Empaquetar
47        if: github.ref == 'refs/heads/main'
48        run: mvn package -DskipTests --no-transfer-progress