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 habilitación de ingeniería y a los gerentes de ingeniería. Muestra cómo diseñar ejercicios de revisión de código que desarrollen esa habilidad de forma intencionada, en lugar de esperar que los revisores la seleccionen de la cola. Cubre el problema de rendimiento, las deficiencias a 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. Pida a ingenieros sénior que validen cada caso, defecto y criterio antes de usarlo.
¿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
| Pregunta | Respuesta corta |
|---|---|
| ¿Cuál es la tarea? | Explique los resultados de la revisión y proporcione comentarios que el autor pueda tener en cuenta. |
| ¿Qué puntuación obtienes? | Precisión de los resultados y utilidad de la explicación. |
| ¿Basta con contar los defectos? | No. Las revisiones abarcan más que solo defectos, por lo que un ejercicio que premia únicamente la cantidad de errores fomenta un mal hábito. |
| ¿Cuál es la demanda cognitiva? | Analiza y evalúa un diseño, y luego crea una sugerencia mejor. |
| ¿Quién valida el caso? | Un gerente de ingeniería o un ingeniero sénior responsable del código fuente. |
| ¿Qué no pueden solucionar los ejercicios? | Tiempo de revisión, propiedad poco clara y presión para fusionarse rápidamente. |
| ¿Cómo sabes que funcionó? | Un cambio nuevo e imperceptible, revisado según criterios acordados, además de un seguimiento de las revisiones reales. |
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.
La investigación sobre la revisión de código moderna respalda la idea de ir más allá de la 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 la gente esperaba. También proporcionaban otros beneficios, como el intercambio de conocimientos, la concienciación del equipo y las soluciones alternativas, y los investigadores describieron la comprensión del código y los cambios como el aspecto clave de la revisión.Bacchelli y Bird, ICSE 2013Se trata de un estudio de los equipos de una sola empresa, así que úselo como un motivo para diseñar soluciones que fomenten la comprensión, no como una referencia para el suyo.
El estándar de revisión publicado por Google apunta en la misma dirección. Indica a los revisores que favorezcan la aprobación de un cambio una vez que mejore definitivamente la salud general del código, incluso si no es perfecto, y dice que la revisión puede enseñar algo nuevo a los desarrolladores, por lo que los comentarios que ayudan a alguien a aprender son bienvenidos.Prácticas de ingeniería de GoogleAmbas 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.
- ¿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.
- ¿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.
- ¿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, comprueba 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 tus herramientas. Hazlo a tu propio ritmo y de forma breve. Una simple comprobación de conocimientos solo confirma los requisitos previos y no demuestra que la persona sea capaz de revisar el código.
Práctica. Utilice cambios preparados con una pequeña cantidad de preocupaciones predefinidas 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. Pida al revisor que escriba el comentario que dejaría, clasifique las preocupaciones y diga qué información adicional querría. La lección práctica de CodeRefinery muestra la estructura: las personas abren una solicitud de extracción que contiene un pequeño error tipográfico y un error mayor, luego la revisan como pares (CodeRefinery, Practicando la revisión de código). Crea el tuyo a partir de tu propio código fuente para que las convenciones y las ventajas y desventajas sean reales.
Comentarios. Relaciónalo con las decisiones que tomó el revisor. "Notaste el problema de redondeo, pero tu comentario decía 'esto parece incorrecto' sin especificar qué dato lo causa" es más útil que "encontré 2 de 4".
¿Informació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. Se ha implementado un cambio que añade un cálculo de descuento al 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. Incluye 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 dar su aprobación.
Un primer intento. "Parece estar bien, la prueba se supera. ¿Quizás deberíamos dividirla?" El revisor ha notado algo, pero no ha especificado qué, por qué es importante ni qué se debe hacer. El autor no puede tomar ninguna medida al respecto.
Comentarios 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? La segunda solicitud pide un comentario específico sobre cada inquietud, con la razón y una sugerencia.
Un intento más enérgico. 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 simultáneamente. Sugiero que las reglas de precios se conviertan en una función independiente que podamos probar por separado. La única prueba solo cubre 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 identifica la inquietud, explica el motivo, ofrece 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:
| Criterio | Evidencia observable |
|---|---|
| Ejecución de tareas | Identifica las preocupaciones relevantes en el cambio y registra las pruebas para cada una de ellas. |
| Razonamiento | Explica por qué cada preocupación es importante, ofrece una alternativa y señala lo que aún permanece incierto. |
| Límites | Sigue las normas de revisión del equipo y pide ayuda o información cuando falta autoridad o contexto. |
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 sobre 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.
- 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.
- 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.
- 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 capacita a revisores en código escrito por IA, consulte nuestra guía complementaria sobre Entrenamiento para la revisión de código generado por IAEsa 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.
