QUÉ ES
- Práctica para bajar costo de cambio en código vivo.
- Legibilidad para humanos primero, compilador después.
- Diseño incremental apoyado por refactor continuo.
QUÉ NO ES
- “Código bonito” sin impacto en mantenibilidad.
- Dogma rígido: se aplican principios con contexto.
- Eliminar toda duplicación prematuramente.
Idea central: la métrica real no es “qué tan elegante quedó”, sino cuánta fricción hay para entender, cambiar y desplegar con seguridad.
Un nombre debe explicar por qué existe y qué representa. Si requiere comentario extra para entenderlo, todavía no está bien nombrado.
Ejemplo: activeSubscriptions aporta más que subs.
Nombra clases y métodos con términos del negocio; reduce traducciones mentales entre requisito y código.
Ejemplo: InvoiceOverduePolicy en vez de CheckService.
Palabras vacías como data, info, manager suelen esconder falta de diseño o responsabilidades mezcladas.
Regla: si todo termina en Manager, falta modelado.
MAL VS BIEN — NOMBRES EN CÓDIGO REAL (JAVA)
// Mal: abreviaciones y ruido
public BigDecimal calc(List li, BigDecimal tx) {
BigDecimal r = BigDecimal.ZERO;
for (OrderItem i : li) r = r.add(i.getP().multiply(BigDecimal.valueOf(i.getQ())));
return r.add(tx);
}
// Bien: intención explícita y lenguaje del dominio
public BigDecimal calculateOrderTotal(List items, BigDecimal taxAmount) {
BigDecimal subtotal = BigDecimal.ZERO;
for (OrderItem item : items) {
subtotal = subtotal.add(item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())));
}
return subtotal.add(taxAmount);
}
Si un método valida, transforma, persiste y notifica, no hace “una cosa”: estás acoplando cambios distintos en el mismo lugar.
Aplicación: separar en pasos privados o servicios dedicados.
No mezcles narrativa de negocio con detalles técnicos en el mismo bloque. Mantén cada función en un único nivel de lectura.
Señal de olor: llamadas SQL + reglas de negocio en el mismo método.
Valida payload, consulta BD, aplica reglas, construye DTO y envía email en 70 líneas. Cualquier cambio de infraestructura toca el flujo de negocio.
`validate` → `buildDomainObject` → `persist` → `notify`. Cada paso es reemplazable y testeable por separado.
El código debería mostrar el “qué”; comenta contexto, trade-offs y decisiones no obvias.
Útil: “se usa timeout corto por límite del proveedor X”.
Comentarios obsoletos engañan más que ayudan. Mejor eliminarlos si ya no representan el comportamiento real.
Regla: si cambias lógica, revisa comentarios en el mismo commit.
Un estilo estable (indentación, longitud de líneas, orden) evita discusiones repetidas y acelera revisiones.
Práctica: automatiza con formatter y linting en CI.
Checklist de revisión: ¿el nombre cuenta intención?, ¿la función mezcla niveles de abstracción?, ¿el comentario agrega contexto o repite código?, ¿puedo entender el bloque en 30 segundos?