Ejercicios de revisión de código: cómo utilizar la revisión por pares para desarrollar el análisis y el criterio técnico.

Un desarrollador abre una solicitud de extracción que agrega un cálculo de descuento a un servicio de pago. Las pruebas pasan y la diferencia es mínima. Un revisor la aprueba en dos minutos con un "LGTM". Tres meses después, un compañero necesita modificar la misma función y descubre que mezcla reglas de precios, redondeo y acceso a la base de datos en un mismo lugar. Nadie puede afirmar con certeza qué está permitido hacer.

Este es un ejemplo ilustrativo, no un incidente documentado. Muestra lo que debe producir la revisión de código entre pares cuando funciona como una actividad de aprendizaje: un revisor que puede ver un cambio plausible, detectar el problema que aún no es un error y explicarlo de manera que el autor pueda actuar en consecuencia.

Esta guía está dirigida a los responsables de capacitación en ingeniería y a los gerentes de ingeniería. Muestra cómo diseñar ejercicios de revisión de código que desarrollen esta habilidad de forma intencionada, en lugar de esperar que los revisores la adquieran espontáneamente. Cubre el problema del rendimiento, las deficiencias que se deben diagnosticar, cómo estructurar la preparación y la práctica, un ejemplo práctico y cómo comprobar que la habilidad se aplica a revisiones reales. Solicita a ingenieros sénior que validen cada caso, defecto y criterio antes de utilizarlo.

¿Qué son los ejercicios de revisión de código?

Los ejercicios de revisión de código son tareas prácticas estructuradas en las que un desarrollador revisa un cambio preparado, explica sus hallazgos y su relevancia, y recibe retroalimentación sobre la calidad de su explicación. Son diferentes de las revisiones que realiza su equipo a diario. El cambio se elige con antelación, se conocen sus posibles problemas y el objetivo es mejorar las habilidades del revisor, en lugar de simplemente implementar el cambio.

Datos Rápidos

1. Describa el problema de rendimiento.

Comience con la tarea, en una sola frase: dado un cambio, el revisor explica qué encontró, por qué es importante y qué podría hacer el autor al respecto. La palabra clave es "explica". Detectar un problema es la mitad de la habilidad. Expresarlo de manera que un colega con una perspectiva diferente pueda comprenderlo, evaluarlo y actuar es la otra mitad.

Las investigaciones sobre la revisión de código moderna respaldan la idea de ir más allá de la simple búsqueda de errores. En un estudio realizado en Microsoft, Bacchelli y Bird observaron, entrevistaron y encuestaron a desarrolladores y gerentes. Descubrieron que encontrar defectos seguía siendo la principal motivación para la revisión, pero que las revisiones se centraban menos en los defectos de lo que se esperaba. También aportaron otros beneficios, como el intercambio de conocimientos, la concienciación del equipo y la búsqueda de soluciones alternativas. Los investigadores describieron la comprensión del código y los cambios como el aspecto clave de la revisión ( Bacchelli y Bird, ICSE 2013 ). Se trata de un estudio de los equipos de una sola empresa, así que utilícelo como argumento para diseñar sistemas que fomenten la comprensión, no como referencia para los suyos.

El estándar de revisión publicado por Google apunta en la misma dirección. Indica a los revisores que prioricen la aprobación de un cambio una vez que mejore de forma definitiva la salud general del código, incluso si no es perfecto, y señala que la revisión puede enseñar algo nuevo a los desarrolladores, por lo que se agradecen los comentarios que ayuden a alguien a aprender ( Prácticas de Ingeniería de Google ). Ambas fuentes describen la revisión como un espacio donde se ejerce y se transmite el juicio. Eso es lo que deberían practicar tus ejercicios.

2. Diagnosticar las deficiencias de aprendizaje y contexto.

Compara la tarea con lo que tu programa actual practica y evalúa.

1. ¿La práctica actual utiliza la tarea real? Si los nuevos revisores aprenden leyendo una guía de estilo y luego revisando solicitudes de extracción reales, practican en un entorno de trabajo real sin margen de error. Si la evaluación consiste en un cuestionario sobre etiqueta en las revisiones, mide la memorización de las reglas, no la capacidad de aplicarlas a un cambio.
2. ¿Cuál es la demanda cognitiva? En la taxonomía de Bloom revisada, juzgar si un diseño es sólido y sopesar sus ventajas y desventajas se sitúa en los niveles de análisis y evaluación, y proponer una mejor estructura alcanza el nivel de creación. Si sus ejercicios solo preguntan "¿qué hace este código?", se detienen en la comprensión. Nuestra guía para relacionar las actividades de aprendizaje con la taxonomía de Bloom. Muestra cómo adaptar la actividad al nivel.
3. ¿Hay algo más que la habilidad que esté interfiriendo? Verifica el tiempo de revisión, las herramientas, la responsabilidad y las normas del equipo. Si los revisores disponen de cinco minutos por solicitud de extracción, ningún ejercicio generará una explicación detallada. Si los autores interpretan cada comentario como una crítica, los revisores suavizarán sus conclusiones hasta que guarden silencio. Informa de estas causas a quienes puedan solucionarlas.

3. Preparación del diseño, práctica y retroalimentación

Asigne una tarea independiente a cada etapa.

Preparación. Antes de empezar, compruebe qué necesitan los revisores: la lista de verificación del equipo, los principios de diseño en los que se basa y cómo interpretar las diferencias en sus herramientas. Mantenga un ritmo flexible y sea breve. Una simple comprobación de conocimientos previos solo confirma los requisitos y no demuestra que la persona sea capaz de realizar una revisión.

Practica. Usa cambios preparados con una pequeña cantidad de problemas predefinidos de diferentes tipos: un error de corrección, un problema de mantenibilidad como las responsabilidades mixtas en el ejemplo inicial, un nombre poco claro o una prueba faltante, y algo de código que esté bien. Pídele al revisor que escriba el comentario que dejaría, clasifique los problemas y diga qué información adicional necesitaría. La lección práctica de CodeRefinery muestra el formato: las personas abren una solicitud de extracción que contiene una pequeña errata y un error mayor, luego la revisan como pares ( CodeRefinery, Practicing code review ). Crea la tuya a partir de tu propio código base para que las convenciones y las compensaciones sean reales.

Comentarios. Vincúlelos con las decisiones que tomó el revisor. "Notaste el problema del redondeo, pero tu comentario decía 'esto parece incorrecto' sin especificar qué dato lo causa" es más útil que "encontré 2 de 4".

¿Retroalimentación en tiempo real o revisión asíncrona? La retroalimentación en tiempo real aporta mayor valor cuando una inquietud es ambigua y los revisores aprenden al escuchar a un ingeniero sénior explicar por qué la plantearía o la descartaría. La revisión asíncrona es suficiente para comparar los comentarios con la revisión anotada de un experto.

4. Analice un ejemplo realista.

A modo de ejemplo, un gerente de ingeniería debe validar el caso y los criterios de respuesta antes de su uso.

El caso. Un cambio añade un cálculo de descuento a un servicio de pago. Supera las pruebas. En una función, aplica descuentos porcentuales y fijos, redondea el resultado, lo guarda en la base de datos y envía un evento. Tiene una prueba, para un único descuento porcentual.

La tarea. El revisor escribe los comentarios que dejaría, clasifica sus preocupaciones y dice lo que necesitaría saber antes de aprobar.

Primer intento. «Parece correcto, la prueba se supera. ¿Quizás deberíamos dividirlo?». El revisor ha notado algo, pero no ha especificado qué, por qué es importante ni qué se debe hacer. El autor no puede tomar medidas al respecto.

Retroalimentación y reintento. El facilitador pregunta: ¿Qué riesgos conllevaría un cambio futuro en esta función? ¿Qué le pediría al autor que agregara antes de aprobarla? El reintento solicita un comentario específico sobre cada inquietud, con la razón y una sugerencia.

Un intento más sólido. "La función aplica dos tipos de descuento, redondea, guarda y publica un evento, por lo que un cambio en el redondeo podría alterar lo que almacenamos y lo que publicamos al mismo tiempo. Solicitaría que las reglas de precios se trasladaran a una función pura que podamos probar por separado. La única prueba cubre solo un descuento porcentual. Solicitaría un descuento fijo y un pedido que reduzca el total a cero. No estoy seguro de si el evento debe activarse cuando el total es cero, así que consultaría con el autor." Nótese que este comentario nombra la preocupación, da la razón, hace una sugerencia concreta y señala lo que el revisor desconoce.

5. Evaluar la capacidad y planificar la transferencia

La evidencia de capacidad se manifiesta en el desempeño ante un cambio nuevo que el revisor no ha visto. Califique la precisión de los hallazgos y la utilidad de la explicación. Una rúbrica simple utiliza una escala de 0 a 2 por criterio:

Anclajes: 0 significa ausente o sin respaldo, 1 significa parcial con omisiones relevantes y 2 significa completo y justificado según los criterios acordados. Defina los errores críticos por separado, por ejemplo, aprobar un cambio con riesgo de pérdida de datos, para que una buena puntuación general no pueda ocultar uno. Adapte los criterios con el gerente de ingeniería; esta rúbrica es una propuesta inicial, no un estándar de preparación validado. Para obtener más información sobre el razonamiento de puntuación, consulte nuestra guía para diseñar prácticas interactivas con retroalimentación útil.

Planifique la transferencia. Tras el ejercicio, revise una muestra de las revisiones reales del evaluador unas semanas después, utilizando los mismos criterios. Compare con una referencia tomada antes de la capacitación y defina la población y el cronograma con anticipación. Analice otros cambios ocurridos durante el mismo período, como una nueva herramienta de evaluación o un cambio de personal, antes de validar los ejercicios.

6. Realiza el ejercicio en directo o a tu propio ritmo con AhaSlides.

Puedes realizar el ejercicio en un taller o dejar que los revisores lo resuelvan por su cuenta. En una sesión en vivo, muestra el cambio preparado y utiliza diapositivas interactivas para el debate.

1. Elegir respuesta Para la pregunta "¿Qué inquietud plantearía primero?", con las inquietudes predefinidas como opciones. Muestre la distribución antes de revelar su propia clasificación.
2. Abierto Para "escribe el comentario que dejarías". Los revisores pueden comparar su redacción con la de otros, y ahí es donde se demuestra la capacidad de explicación.
3. Escala de valoración para "¿qué tan grave es esto?", para que el grupo pueda ver dónde difieren los juicios y hablar sobre el porqué.

Para los revisores que no puedan asistir, pueden usar la misma secuencia a su propio ritmo, con la revisión experta comentada después de cada respuesta. Considere cualquier afirmación sobre la ejecución de código, integraciones o funciones de IA como no confirmada hasta que la haya probado con su propio material.

Si también capacitas a revisores en código escrito por IA, consulta nuestra guía complementaria sobre capacitación en revisión de código generado por IA . Esa publicación trata sobre la auditoría de los resultados generados. Esta trata sobre cómo las personas revisan el trabajo de los demás y cómo explican sus hallazgos.

Restricciones que pueden persistir

• Hora de revisar. Un comentario reflexivo lleva más tiempo que un simple "LGTM", y los plazos de entrega obligan a usar la versión breve.
• Normas del equipo. Si los comentarios se interpretan como críticas personales, los revisores suavizarán o descartarán sus conclusiones.
• Cobertura del caso. Un ejercicio pone de manifiesto varios tipos de preocupación. Una puntuación no refleja el juicio general del evaluador.
• Transferencia El rendimiento en un taller no es lo mismo que el rendimiento en una cola concurrida, así que consulta también las opiniones reales.

Comuniquen estos problemas a los patrocinadores con anticipación y planifiquen soluciones específicas. Los ejercicios mejoran la capacidad de observación y explicación del revisor, pero no establecen el tiempo ni las normas.

Preguntas frecuentes

¿Qué son los ejercicios de revisión de código?

Se trata de tareas prácticas preparadas en las que un desarrollador revisa un cambio con problemas conocidos, escribe los comentarios que dejaría y recibe retroalimentación sobre su precisión y utilidad. El objetivo es desarrollar la habilidad del revisor, no implementar el cambio.

¿Cómo se evalúa si el criterio de un revisor ha mejorado?

Propóngales un cambio novedoso que no hayan visto y evalúe los resultados y la explicación según criterios acordados. Luego, revise una muestra de reseñas reales unas semanas después. Un cuestionario sobre las reglas de revisión solo confirma los requisitos previos.

¿La revisión de código entre pares consiste principalmente en encontrar errores?

Encontrar defectos sigue siendo una motivación principal, pero un estudio de Microsoft reveló que las revisiones se centraban menos en los defectos de lo esperado y también fomentaban el intercambio de conocimientos y la concienciación del equipo. Se recomienda diseñar ejercicios que recompensen la explicación y la comprensión, además del recuento de defectos.

Por dónde empezar

Elija un tipo de cambio que su equipo revise con frecuencia. Redacte la declaración de desempeño, pida a un ingeniero sénior que prepare un cambio con tres o cuatro preocupaciones iniciales y elabore una rúbrica de tres criterios con una escala de 0 a 2 y una lista de errores críticos. Realice una prueba piloto con un grupo pequeño y luego compare sus próximas revisiones reales con una referencia.

Para ver cómo se puede realizar un ejercicio de revisión en directo con tu propio equipo y reutilizarlo posteriormente a tu propio ritmo, explora AhaSlides.