affaan-m--everything-claude-code/docs/es/rules/common/coding-style.md

# Estilo de Código

## Inmutabilidad (CRÍTICO)

SIEMPRE crear objetos nuevos, NUNCA mutar los existentes:

```
// Pseudocódigo
INCORRECTO:  modify(original, campo, valor) → modifica original in-place
CORRECTO:    update(original, campo, valor) → retorna nueva copia con el cambio
```

Justificación: Los datos inmutables previenen efectos secundarios ocultos, facilitan la depuración y permiten concurrencia segura.

## Principios Fundamentales

### KISS (Keep It Simple)

- Preferir la solución más simple que realmente funcione
- Evitar optimización prematura
- Optimizar para claridad, no para ingeniosidad

### DRY (Don't Repeat Yourself)

- Extraer lógica repetida en funciones o utilidades compartidas
- Evitar la deriva por copiar y pegar implementaciones
- Introducir abstracciones cuando la repetición es real, no especulativa

### YAGNI (You Aren't Gonna Need It)

- No construir features o abstracciones antes de que sean necesarias
- Evitar generalidad especulativa
- Comenzar simple, luego refactorizar cuando la presión es real

## Organización de Archivos

MUCHOS ARCHIVOS PEQUEÑOS > POCOS ARCHIVOS GRANDES:
- Alta cohesión, bajo acoplamiento
- 200-400 líneas típico, 800 máximo
- Extraer utilidades de módulos grandes
- Organizar por feature/dominio, no por tipo

## Manejo de Errores

SIEMPRE manejar errores de forma exhaustiva:
- Manejar errores explícitamente en cada nivel
- Proporcionar mensajes de error amigables en código orientado a la UI
- Registrar contexto detallado del error en el lado del servidor
- Nunca silenciar errores

## Validación de Entrada

SIEMPRE validar en los límites del sistema:
- Validar toda la entrada del usuario antes de procesarla
- Usar validación basada en esquemas donde esté disponible
- Fallar rápido con mensajes de error claros
- Nunca confiar en datos externos (respuestas de API, entrada de usuario, contenido de archivos)

## Convenciones de Nomenclatura

- Variables y funciones: `camelCase` con nombres descriptivos
- Booleanos: preferir prefijos `is`, `has`, `should`, o `can`
- Interfaces, tipos y componentes: `PascalCase`
- Constantes: `UPPER_SNAKE_CASE`
- Custom hooks: `camelCase` con prefijo `use`

## Code Smells a Evitar

### Anidamiento Profundo

Preferir retornos anticipados sobre condicionales anidados cuando la lógica empieza a acumularse.

### Números Mágicos

Usar constantes nombradas para umbrales, retrasos y límites significativos.

### Funciones Largas

Dividir funciones grandes en piezas enfocadas con responsabilidades claras.

## Lista de Verificación de Calidad de Código

Antes de marcar el trabajo como completo:
- [ ] El código es legible y bien nombrado
- [ ] Las funciones son pequeñas (<50 líneas)
- [ ] Los archivos están enfocados (<800 líneas)
- [ ] Sin anidamiento profundo (>4 niveles)
- [ ] Manejo de errores apropiado
- [ ] Sin valores hardcodeados (usar constantes o configuración)
- [ ] Sin mutación (patrones inmutables usados)