La Lista de Verificación de Revisión de Código que Creé Después de 2,000 Solicitudes de Extracción

Clasifiqué 2,147 comentarios de PR que dejé durante 18 meses. El 34% eran sobre manejo de errores. El 22% eran sobre nombres. Solo el 8% sobre rendimiento. Esto no era lo que esperaba cuando empecé a hacer seguimiento de mis revisiones. Pensé que estaría detectando problemas arquitectónicos y errores complejos. En cambio, señalaba repetidamente los mismos problemas fundamentales: falta de comprobaciones de nulos, nombres de variables vagos y mensajes de error que no le decían nada útil a los usuarios. Después de ver los mismos problemas surgir en incidentes en producción, me di cuenta de que no eran pequeñas críticas; eran la diferencia entre sistemas que fallan de manera controlada y sistemas que te despiertan a las 3 AM.

Por qué La Mayoría de las Listas de Verificación de Revisión de Código Fallan en el Punto

Todos te dicen que verifiques el estilo de código, la cobertura de pruebas y la documentación. Eso está bien, pero no es donde falla la producción. Las listas de verificación que veo compartidas en blogs de ingeniería se centran en lo que es fácil de medir en lugar de lo que realmente importa. Te dirán que verifiques que las funciones tengan menos de 50 líneas, pero no te dirán que revises si el manejo de errores realmente ayuda a alguien a depurar el problema a las 2 AM cuando los registros son tu único amigo.

Las mejores revisiones de código no solo previenen errores; previenen el tipo de errores que se convierten en incidentes. Una falta de comprobación de nulos no es solo un posible bloqueo; es un posible evento de corrupción de datos cuando ese bloqueo ocurre en medio de una transacción.

Empecé a rastrear mis comentarios de PR porque estaba frustrado. Revisaba código, lo aprobaba y luego veía al mismo desarrollador cometer el mismo error en la siguiente PR. La retroalimentación no se estaba asimilando. Así que creé una hoja de cálculo. Cada comentario que dejaba se categorizaba: manejo de errores, nombres, pruebas, seguridad, rendimiento, arquitectura u otros. Después de seis meses, tuve suficientes datos para ver patrones. Después de dieciocho meses, esos patrones se habían consolidado en una lista de verificación que realmente funcionaba.

Lo sorprendente no fue solo qué encabezaba la lista, sino lo que no lo hacía. Los comentarios de optimización de rendimiento representaron solo el 8% de mis revisiones. Los problemas de seguridad fueron el 6%. Estas son las cosas en las que obsesionamos en discusiones arquitectónicas, pero en PRs del día a día, son raras. ¿Qué es común? Desarrolladores asumiendo el camino feliz, nombrando las cosas mal, y escribiendo mensajes de error para ellos mismos en lugar de para la persona que estará depurando a medianoche.

Los Patrones de Manejo de Errores que Siguen Rompiendo la Producción

Aquí está mi lista numerada de problemas de manejo de errores, clasificados por la frecuencia con la que causan incidentes reales:

1. Fallos silenciosos en trabajos de fondo. El código captura una excepción, la registra y continúa. Parece razonable hasta que te das cuenta de que ese trabajo debía enviar un correo electrónico de confirmación de pago. Ahora tu cliente piensa que no le cobraron, pero sí le cobraron. Veo este patrón en el 40% de las PRs de trabajos de fondo. La solución es simple: si la operación es crítica, no captures la excepción; deja que suba y active tu alerta. Si no es crítica, documenta por qué está bien fallar silenciosamente.
2. Mensajes de error genéricos que ocultan el contexto. "Ocurrió un error" no me dice nada. "No se pudo procesar el pago" es mejor pero aún inútil. "No se pudo cobrar a la tarjeta terminando en 4242: fondos insuficientes (código de error: tarjeta_rechazada)" realmente ayuda. Este aspecto lo señalo en aproximadamente el 30% de las PRs. La prueba que utilizo: si ves este error en los registros de producción a las 3 AM, ¿podrías diagnosticarlo sin agregar más registros y redeplegar?
3. Captura de Exception en lugar de excepciones específicas. Esto es controvertido porque algunas guías de estilo lo recomiendan, pero he visto que oculta errores demasiadas veces. Cuando capturas Exception, también estás capturando NullPointerException, IllegalStateException, y todas las demás excepciones que indican error del programador en lugar de condiciones de tiempo de ejecución. Captura lo que esperas manejar. Deja que los errores del programador causen fallos; así es como los encuentras.
4. No validar datos externos en el límite. Respuestas de API, entrada del usuario, contenidos de archivos; si proviene de fuera de tu proceso, validalo inmediatamente. Veo a desarrolladores validar en la capa de lógica empresarial, lo que significa que los datos no válidos ya se han propagado a través de varias funciones. Para entonces, estás depurando por qué un valor nulo llegó a tu base de datos. Valida en el límite, falla rápido, devuelve errores claros.
5. Logica de reintento sin retroceso exponencial. El servicio está caído, así que intentas de nuevo inmediatamente. Sigue caído, así que lo intentas de nuevo de inmediato. Felicitaciones, acabas de transformar una degradación del servicio en una interrupción completa al bombardearlo con reintentos. Veo esto en el 15% de las PRs que añaden lógica de reintento. Siempre usa retroceso exponencial con jitter. Siempre ten un conteo máximo de reintentos. Siempre considera si reintentar tiene sentido para esta operación.
6. No manejar fallos parciales en operaciones por lotes. Estás procesando 1,000 registros. El registro 500 falla. ¿Qué pasa con los registros 501-1000? En la mayoría del código que reviso, nunca se procesan. El lote falla, se reintenta, falla nuevamente en el registro 500, y quedas atrapado. Maneja los fallos parciales explícitamente: rastrea qué tuvo éxito, qué falló y por qué. Haz que tus operaciones por lotes sean reanudables.
7. Asumir que las transacciones de base de datos siempre tendrán éxito. Inicias una transacción, haces algún trabajo y la confirmas. Pero, ¿qué pasa si la confirmación falla? ¿Qué pasa si pierdes la conexión a la base de datos en medio de la transacción? Veo código que no maneja esto en el 25% de las PRs que tocan código de base de datos. El resultado: el estado de tu aplicación y el estado de la base de datos divergen, y pasas horas depurando por qué los datos no coinciden con lo que dicen los registros que sucedió.

El Día en que un Nombre de Variable Provocó un Incidente de $50,000

Era un martes por la mañana cuando recibí el mensaje de Slack: "Acabamos de reembolsar $50,000 a los clientes equivocados." Abrí el canal de incidentes y empecé a leer. Un desarrollador había enviado una solución la noche anterior para un error en nuestro sistema de procesamiento de reembolsos. La solución era una línea. La PR había sido aprobada por dos ingenieros senior. Las pruebas pasaron. Todo parecía bien.

El error estaba en un nombre de variable. El código original tenía una variable llamada `refundAmount` que representaba el monto a reembolsar en centavos. El desarrollador agregó una nueva variable llamada `refundAmount` que representaba el monto en dólares. Olvidaron renombrar la variable original. El código se compiló bien; ambas eran enteros. Las pruebas pasaron porque los datos de prueba usaron cantidades donde los centavos y los dólares estaban lo suficientemente cerca como para que las afirmaciones no lo detectaran.

En producción, procesamos 200 reembolsos esa mañana. La mitad de ellos eran por el monto incorrecto. Un reembolso de $10.00 se convirtió en un reembolso de $1,000. Un reembolso de $5.00 se convirtió en un reembolso de $500. Para cuando alguien se dio cuenta, habíamos pagado de más $50,000. Tuvimos que revisar manualmente cada reembolso, contactar a los clientes y, en algunos casos, pedir que regresaran el dinero. Tomó tres días limpiarlo.

La causa raíz no fue el error del desarrollador; todos cometen errores. Fue que teníamos dos variables con el mismo nombre representando diferentes unidades en el mismo alcance. La revisión de código no lo detectó porque los revisores estaban enfocados en la lógica, no en el nombramiento. Después de ese incidente, añadí una regla a mi lista de verificación: si una variable representa una cantidad con unidades, la unidad debe estar en el nombre. No `amount`, sino `amountCents` o `amountDollars`. No `duration`, sino `durationSeconds` o `durationMilliseconds`.

Esto parece pedante...