Cultura de code review: feedback que realmente ayuda

Por qué la revisión de código le falla a los equipos

La revisión de código es una de las actividades con mayor impacto en el desarrollo de software. Bien hecha, difunde conocimiento, detecta errores y mejora el diseño. Mal hecha, genera resentimiento, ralentiza las entregas y no le enseña nada a nadie.

He visto ambas. Esto es lo que las distingue.

Los cuatro tipos de comentarios en una revisión

No todo el feedback vale lo mismo. Ser explícito sobre el peso de un comentario reduce la fricción.

nit: Minor style preference, author can ignore or fix
     "nit: I'd name this `userCount` instead of `count` for clarity"

suggestion: My recommendation, but I understand if you disagree
            "suggestion: Could we extract this into a separate function?"

question: Genuine curiosity, not a disguised criticism
          "question: Why do we need to fetch this on every render?"

blocker: Must be addressed before merging
         "blocker: This will panic on nil input — we need a guard here"

Cuando no etiquetas tus comentarios, el autor tiene que adivinar si estás bloqueando o solo matizando. Esa ambigüedad genera ansiedad y alarga el ciclo de revisión.

En qué se equivocan los revisores

Revisar el estilo, no el fondo

Los debates de estilo (tabulaciones contra espacios, tipo de comillas, convenciones de nombres) deberían automatizarse. Si tu linter y tu formatter no lo detectan, añade una regla. El tiempo de un revisor humano es demasiado valioso para gastarlo en formato.

# These should never appear in a code review comment
# Configure once, enforce automatically
npx eslint --init
npx prettier --write .
npx tsc --noEmit

Si te encuentras escribiendo "usa comillas dobles aquí" en una revisión, detente y añade una regla de Prettier en su lugar.

Reescribir, no revisar

La diferencia entre dar feedback y pedir una reescritura:

// ❌ "Just rewrite it like this:"
// Reviewer pastes a 40-line refactor
 
// ✅ Explain the principle, offer the option
// "This function is doing three things — validation, transformation, and persistence.
// Could we split it into smaller functions? I'm happy to pair on this if helpful."

El autor aprende más entendiendo el principio que copiando tu solución.

Revisiones al pasar

Una revisión que solo detecta errores de sintaxis e ignora las cuestiones de arquitectura está incompleta. Una revisión que se obsesiona con los nombres de las variables e ignora una comprobación de seguridad ausente es peligrosa.

La jerarquía de la revisión:

1. Corrección — ¿hace lo que afirma hacer?
2. Seguridad — ¿maneja entradas no confiables de forma segura?
3. Rendimiento — ¿hay ineficiencias evidentes a escala?
4. Diseño — ¿la abstracción es apropiada?
5. Legibilidad — ¿puede entenderlo el próximo desarrollador?
6. Estilo — ¿es consistente con el código base? (automatiza esto)

La mayoría de los comentarios de estilo pertenecen al nivel 6. La mayoría de las discusiones en los PR ocurren en el nivel 6.

En qué se equivocan los autores

Pull requests gigantes

Un PR de 3.000 líneas recibirá una revisión superficial. Los revisores pierden motivación, se saltan secciones y aprueban por agotamiento.

Objetivo: menos de 400 líneas modificadas por PR. Para funcionalidades grandes:

• Feature flags — integra incrementalmente detrás de un flag
• PRs apilados — base → abstracción → funcionalidad
• Interfaz primero — define el contrato, luego implementa

# ❌ One monolithic PR
[FEATURE] Add e-commerce checkout flow (3,247 lines changed)

# ✅ Decomposed into reviewable chunks
[1/4] Add cart data model and repository layer (280 lines)
[2/4] Add cart API endpoints with validation (310 lines)
[3/4] Add checkout UI components (420 lines)
[4/4] Wire checkout flow end-to-end (180 lines)

Cada PR se puede integrar de forma independiente y cuenta una historia completa.

Malas descripciones de PR

La descripción de un PR es la carta de presentación de tu código. Debería responder:

• ¿Qué hace este cambio?
• ¿Por qué es este el enfoque correcto?
• ¿Qué alternativas se consideraron?
• ¿Cómo puede probarlo el revisor?
• ¿En qué debería fijarse primero?

## What
 
Adds rate limiting to the public API endpoints to prevent abuse.
 
## Why
 
We've seen automated scraping causing load spikes on `/api/products`.
Limiting to 100 req/min per IP address matches industry norms for public APIs.
 
## Approach
 
Using Redis sliding window with `rate-limiter-flexible`.
Considered IP-based vs API-key-based — went with IP for now since we don't
have API keys yet, and can layer key-based later.
 
## Testing
 
- Run `npm run test:rate-limit` to see the rate limiting behavior
- Or hit the endpoint 110 times in rapid succession in dev
 
## Areas to focus on
 
- The Redis key structure (line 47) — I'm not sure it's optimal
- Error response format (line 89) — should match our existing error shape?

Construir una cultura de revisión saludable

Responde en menos de 24 horas. Los PR estancados desmotivan y crean conflictos de merge. Si no puedes revisar hoy, dilo.

Separa la revisión de la aprobación. Puedes dejar comentarios sin bloquear el PR. Usa "Request changes" solo para bloqueos reales.

Celebra el buen código. Las revisiones no sirven solo para encontrar problemas.

// "Really elegant approach to the retry logic here — borrowing this pattern."
// "Nice catch on the edge case in the empty array handling."

Presume buena fe. El autor tomó decisiones razonables dado su contexto. Primero preguntas, después conclusiones.

Mantén el alcance acotado. Si notas problemas ajenos mientras revisas, crea issues separados: no amplíes el alcance del PR.

La mejor revisión de código que he recibido me enseñó un patrón nuevo, validó mi enfoque y me dejó con ganas de seguir trabajando. Ese es el estándar.