A good code review improves the system. A bad code review only adds friction.
Common problem
Senior teams usually fall into two extremes:
- superficial review for “move tickets”,
- eternal review with comments of personal preference.
Neither of them works.
Fast framework (3 layers)
Layer 1: Correctness and risk
- breaks functional flow?
- handles real errors?
- does it affect security or data?
Layer 2: Maintainability
- clear names and structure?
- unnecessary duplication?
- justified technical debt?
Layer 3: Evolution
- facilitates future changes?
- sufficient observability?
- correct tests for the risk of change?
Golden rule
Comment on impact, not ego.
Instead of: “I would do it differently”
Better: “this decision increases accidental complexity by X, I propose Y by Z.”
Practical PR comment template
Use a short format so that each comment has context, impact and action:
### [Bloqueante] Validacion de input ausente
- Contexto: `createUser()` guarda datos directos del request.
- Riesgo: podemos persistir email invalido y romper notificaciones.
- Sugerencia: validar formato antes de persistir.
```ts
if (!isValidEmail(payload.email)) {
throw new BadRequestError("invalid email");
}```
- Evidencia: el test `user-create-invalid-email` falla sin esta validacion.If it is not blocking, clearly mark the priority level:
- [No bloqueante] renombrar `data` -> `userProfile` para legibilidad.
- [No bloqueante] extraer `buildResponse()` para reducir duplicacion.Suggested review SLA
- Small PR: < 24h
- Median PR: < 48h
- Large PR: divide into slices
Quality does not depend on taking longer; It depends on reviewing with focus.
PR description template (to facilitate review)
## Que cambia
- Agrega endpoint `POST /users`.
- Agrega validacion de payload y tests de contrato.
## Riesgo
- Medio: toca flujo de registro.
## Como probar
1. `npm test -- user-create`
2. `curl -X POST /users ...` con payload valido e invalido.
## Rollback
- Revertir commit + redeploy.Integration with AI (without losing criteria)
You can use AI for pre-review and detection of repetitive patterns, but the final decision must be human.
/en/blog/28-code-review-asistido-por-ia-que-si-y-que-no//blog/20-understanding-story-points-agile-estimation/- Engineering Culture Hub:
/blog/category/engineering-culture/
Closing
Effective review = better architecture + fewer incidents + better team learning. That combination pays for itself.
Happy reading! ☕
Comments