# Regla: Estilo de Código Java (Java 17+)
Esta regla es OBLIGATORIA para todo código Java nuevo o modificado.
Java moderno (17+) ofrece construcciones que eliminan verbosidad sin sacrificar
claridad. Usarlas no es opcional: reducen bugs y aumentan legibilidad.
---
## Formateador obligatorio
- Usar **google-java-format** o **Spotless** con perfil AOSP (4 espacios).
Alternativa aceptable: Checkstyle con configuración de Google Style Guide.
- El formateador corre en CI como verificación bloqueante. Un PR que no formatea
no pasa la pipeline sin importar el resto.
- Configurar el IDE para formatear al guardar. No formatear manualmente.
```xml
com.diffplug.spotless
spotless-maven-plugin
2.43.0
1.19.2
```
---
## Records para DTOs inmutables (Java 16+)
Los records eliminan el boilerplate de DTOs. Todo DTO inmutable DEBE ser record.
```java
// MAL — clase tradicional con boilerplate innecesario
public class UsuarioDto {
private final String nombre;
private final String email;
public UsuarioDto(String nombre, String email) { ... }
public String getNombre() { return nombre; }
// ... equals, hashCode, toString
}
// BIEN — record: inmutable, compacto, con equals/hashCode/toString automáticos
public record UsuarioDto(String nombre, String email) {}
```
---
## Sealed classes para jerarquías cerradas (Java 17+)
Cuando una jerarquía tiene un número fijo conocido de subtipos, usar `sealed`.
Permite al compilador verificar exhaustividad en switch expressions.
```java
// BIEN
public sealed interface ResultadoPago
permits PagoAprobado, PagoRechazado, PagoPendiente {}
public record PagoAprobado(String transaccionId) implements ResultadoPago {}
public record PagoRechazado(String motivo) implements ResultadoPago {}
public record PagoPendiente(Instant expiracion) implements ResultadoPago {}
// Switch exhaustivo — el compilador verifica que todos los casos están cubiertos
String mensaje = switch (resultado) {
case PagoAprobado a -> "Aprobado: " + a.transaccionId();
case PagoRechazado r -> "Rechazado: " + r.motivo();
case PagoPendiente p -> "Pendiente hasta " + p.expiracion();
};
```
---
## Pattern matching para instanceof (Java 16+)
```java
// MAL — cast manual redundante
if (objeto instanceof Factura) {
Factura factura = (Factura) objeto;
procesar(factura);
}
// BIEN — pattern matching elimina el cast
if (objeto instanceof Factura factura) {
procesar(factura);
}
```
---
## Text blocks para strings multilínea (Java 15+)
```java
// MAL — concatenación ilegible
String sql = "SELECT f.id, f.total\n" +
"FROM facturas f\n" +
"WHERE f.estatus = 'ACTIVA'\n" +
"ORDER BY f.fecha_emision DESC";
// BIEN — text block preserva indentación y legibilidad
String sql = """
SELECT f.id, f.total
FROM facturas f
WHERE f.estatus = 'ACTIVA'
ORDER BY f.fecha_emision DESC
""";
```
---
## Optional: uso correcto
- `Optional` es para valores de RETORNO que pueden estar ausentes. Solo ahí.
- NUNCA como parámetro de método — usar sobrecarga o valor por defecto.
- NUNCA como campo de clase — usar null con documentación o valor centinela.
```java
// MAL — Optional como parámetro
public void enviarCorreo(String destinatario, Optional asunto) { ... }
// MAL — Optional como campo
public class Pedido {
private Optional notas; // serialización rota, null es suficiente
}
// BIEN — Optional solo en retorno
public Optional buscarPorEmail(String email) {
return repositorio.findByEmail(email);
}
// BIEN — consumir con métodos funcionales, no con isPresent()/get()
buscarPorEmail(email)
.map(Usuario::getNombre)
.orElse("Anónimo");
```
---
## var para variables locales con tipo obvio
```java
// MAL — tipo redundante cuando el constructor lo hace obvio
HashMap> facturasPorCliente = new HashMap>();
// BIEN — var elimina redundancia sin perder claridad
var facturasPorCliente = new HashMap>();
// MAL — var donde el tipo no es obvio (reduce legibilidad)
var resultado = procesarPedido(id); // ¿Qué tipo retorna procesarPedido?
// BIEN — tipo explícito cuando no es obvio del lado derecho
ResultadoProcesamiento resultado = procesarPedido(id);
```
---
## Campos final y nombres
- Declarar `final` todo campo que no cambia después de la construcción.
- Declarar `final` todo parámetro de método cuando el método es largo.
- Clases: `PascalCase`. Métodos y variables: `camelCase`.
- Constantes: `SCREAMING_CASE` con `static final`.
- Sin abreviaciones salvo las universalmente conocidas (`id`, `dto`, `url`).
```java
// MAL
private String n; // nombre críptico
private int contadorTemporalLogs; // hungarian notation innecesaria
static final int maxReintentos = 3; // constante en camelCase
// BIEN
private final String nombre;
private int contadorLogs;
static final int MAX_REINTENTOS = 3;
```
---
## Límites de tamaño
- Máximo **40 líneas** por método (sin contar líneas en blanco y comentarios).
- Máximo **300 líneas** por clase. Si crece más: extraer clases colaboradoras.
- Máximo **5 parámetros** por método. Si se necesitan más: crear un objeto de parámetros.
---
## Organización de imports
Orden estricto, separados por línea en blanco:
1. `java.*`
2. `javax.*`
3. `jakarta.*`
4. `org.*`
5. `com.*` (librerías externas)
6. Paquetes del proyecto propio
Sin imports con wildcard (`import java.util.*`). Un tipo por línea.
---
## Checklist de estilo Java antes de abrir PR
- [ ] google-java-format / Spotless aplicado — el CI no fallará por formato
- [ ] DTOs inmutables convertidos a records
- [ ] Jerarquías cerradas usan sealed interfaces
- [ ] instanceof con pattern matching (sin cast manual)
- [ ] Optional solo en valores de retorno
- [ ] Constantes en SCREAMING_CASE con static final
- [ ] Sin imports wildcard
- [ ] Métodos <= 40 líneas, clases <= 300 líneas
- [ ] Campos inmutables marcados como final