Revision de Legibilidad de Codigo

El Problema

El codigo se lee diez veces mas de lo que se escribe. Una funcion llamada proc() con ternarios anidados, variables de una letra y sin comentarios fuerza a cada futuro lector a hacer ingenieria inversa de la intencion a partir del comportamiento. Los desarrolladores pasan el 70% de su tiempo leyendo codigo, pero las revisiones se enfocan casi exclusivamente en correctitud e ignoran si el codigo comunica claramente al siguiente humano que lo toca.

El Prompt

Revisa el siguiente codigo por legibilidad. Actua como un lider de equipo evaluando si un desarrollador junior podria entender este codigo sin hacer preguntas.

LENGUAJE: [ej. TypeScript, Python, Go, Java]

CODIGO:
[pegar codigo aqui]

Evalua en estas dimensiones de legibilidad:

1. **Nomenclatura**
   - Variables, funciones y clases se nombran por su proposito (no abreviaciones)?
   - Los nombres booleanos se leen como preguntas (isActive, hasPermission)?
   - Los nombres de colecciones son plurales (users, no userList)?
   - Las constantes son UPPER_SNAKE_CASE y descriptivas?

2. **Diseno de Funciones**
   - Las funciones tienen menos de 20-30 lineas?
   - Cada funcion hace una sola cosa (responsabilidad unica)?
   - Las listas de parametros son cortas (max 3, objetos para mas)?

3. **Complejidad Cognitiva**
   - Cuantos niveles de anidamiento (max 3 recomendado)?
   - Hay ternarios anidados o condicionales encadenados?
   - Los early returns pueden reemplazar anidamiento profundo?

4. **Comentarios & Documentacion**
   - Los comentarios explican POR QUE, no QUE?
   - Los numeros magicos estan extraidos en constantes nombradas?
   - Los algoritmos complejos o reglas de negocio estan explicados?

5. **Estructura & Formato**
   - El codigo relacionado esta agrupado?
   - Se usan lineas en blanco para separar bloques logicos?
   - El archivo tiene longitud razonable (menos de 300 lineas)?
   - Se elimino el codigo muerto / comentado?

Para cada problema, proporciona:
- **Ubicacion**: Archivo y linea
- **Severidad**: Confuso / Poco claro / Nitpick
- **Problema**: Por que un lector tendria dificultades
- **Fix**: Codigo reescrito con legibilidad mejorada

Ejemplo de Salida

## Revision de Legibilidad: 6 problemas encontrados

### Confuso: Nombres de Variables Cripticos
Ubicacion: src/utils/process.ts:7
Codigo: `const r = await fn(d, o.p ? o.p : DEFAULT_P);`
Fix: `const result = await fetchReport(dateRange, options.pageSize ?? DEFAULT_PAGE_SIZE);`

### Confuso: Condicionales Profundamente Anidados
Ubicacion: src/services/auth.ts:23 — 5 niveles de anidamiento
Fix (guard clauses):
  if (!user) return unauthorized();
  if (!user.active) return forbidden('Cuenta inactiva');
  if (!user.verified) return forbidden('Email no verificado');
  // logica real — plana y clara

Cuando Usar

Ejecutar en cada pull request, especialmente codigo escrito bajo presion de tiempo. Particularmente valioso al incorporar nuevos miembros al equipo — codigo legible reduce el tiempo de adaptacion de semanas a dias.

Tips Pro

• Leer el codigo en voz alta — si no puedes hablar naturalmente el nombre de la funcion y parametros como una oracion, la nomenclatura necesita trabajo.
• Pedir version refactorizada — “Reescribe este archivo completo aplicando todas las sugerencias, preservando la funcionalidad exacta.”
• Medir complejidad cognitiva — “Calcula el puntaje de complejidad cognitiva (metodologia SonarQube) para cada funcion.”