He estado haciendo revisiones de código en el día a día durante más de una década. Los beneficios de las revisiones de código son muchos: alguien comprueba tu trabajo en busca de errores, consiguen aprender de tu solución, y la colaboración ayuda a mejorar el enfoque general de la organización en cuanto a herramientas y automatización. Si actualmente no está haciendo revisiones de código en su organización, empiece ahora. Un montón de personas y organizaciones han compartido sus mejores prácticas de revisión de código y lo que significa para ellos la definición de buenas revisiones de código. Las guías de Google, el equipo de SmartBear, y el ingeniero Philipp Hauer son todas excelentes lecturas. A continuación, mi opinión personal sobre cómo son las buenas revisiones de código y cómo mejorarlas a nivel de equipo y de organización. Esto es en el contexto del entorno tecnológico en el que he estado trabajando – actualmente en Uber, y antes de eso en Skype/Microsoft y Skyscanner.
Las buenas revisiones de código son el listón por el que todos deberíamos esforzarnos. Cubren las mejores prácticas comunes y fáciles de seguir con las que cualquier equipo puede empezar, al tiempo que garantizan revisiones de alta calidad y útiles a largo plazo.
Las mejores revisiones de código son aquellas en las que los ingenieros siguen mejorando la forma de hacer revisiones de código. Estas revisiones de código miran el cambio de código en el contexto de la base de código, de quién lo solicita y en qué situación. Estas revisiones ajustan su enfoque en función del contexto y la situación. El objetivo no es sólo una revisión de alta calidad, sino también ayudar a los desarrolladores y equipos que solicitan la revisión a ser más productivos.
Áreas cubiertas por la revisión de código
Las buenas revisiones de código miran el cambio en sí mismo y cómo encaja en el código base. Revisarán la claridad del título y la descripción y el «por qué» del cambio. Cubren la corrección del código, la cobertura de las pruebas, los cambios de funcionalidad, y confirman que siguen las guías de codificación y las mejores prácticas. Señalarán las mejoras obvias, como el código difícil de entender, los nombres poco claros, el código comentado, el código no probado o los casos límite no tratados. También señalarán si se han introducido demasiados cambios en una sola revisión y sugerirán que se mantengan los cambios en el código con un único propósito o que se dividan en partes más concretas.
Las mejores revisiones de código examinan el cambio en el contexto del sistema más amplio y comprueban que los cambios son fáciles de mantener. Pueden hacer preguntas sobre la necesidad del cambio o sobre cómo afecta a otras partes del sistema. Observan las abstracciones introducidas y cómo encajan en la arquitectura de software existente. Anotan las observaciones de mantenibilidad, como la lógica compleja que podría simplificarse, la mejora de la estructura de las pruebas, la eliminación de duplicaciones y otras posibles mejoras. El ingeniero Joel Kemp describe las grandes revisiones de código como un pase contextual que sigue a un pase inicial ligero.
Tono de la revisión
El tono de las revisiones de código puede influir enormemente en la moral de los equipos. Las revisiones con un tono duro contribuyen a crear una sensación de ambiente hostil con sus microagresiones. El lenguaje opinable puede poner a la gente a la defensiva, provocando discusiones acaloradas. Al mismo tiempo, un tono profesional y positivo puede contribuir a crear un entorno más inclusivo. La gente en estos entornos está abierta a la retroalimentación constructiva y las revisiones de código pueden desencadenar discusiones sanas y animadas.
Las buenas revisiones de código hacen preguntas abiertas en lugar de hacer declaraciones fuertes o de opinión. Ofrecen alternativas y posibles soluciones que podrían funcionar mejor para la situación sin insistir en que esas soluciones son la mejor o la única manera de proceder. Estas revisiones asumen que el revisor podría estar pasando algo por alto y piden aclaraciones en lugar de correcciones.
Las mejores revisiones de código también son empáticas. Saben que la persona que escribe el código ha invertido mucho tiempo y esfuerzo en este cambio. Estas revisiones de código son amables y sin pretensiones. Aplauden las buenas soluciones y son positivas en general.
Aprobar vs. Solicitar cambios
Una vez que un revisor completa su revisión, puede marcarla como aprobada, bloquear la revisión con solicitudes de cambio, o no establecer un estado específico, dejándola en un estado «aún no aprobado». La forma en que los revisores utilizan los estados de aprobación y solicitud de cambios es reveladora de las revisiones de código.
Las buenas revisiones de código no aprueban los cambios mientras haya preguntas abiertas. Sin embargo, dejan claro qué preguntas o comentarios no son de bloqueo o no son importantes, marcándolos de forma distintiva. Son explícitos a la hora de aprobar un cambio – por ejemplo, añadiendo un comentario de pulgar hacia arriba como «¡se ve bien!». En algunos lugares se utilizan acrónimos como LGTM, que también funcionan, pero hay que tener en cuenta que los recién llegados pueden malinterpretar estos acrónimos internos por otra cosa. Las buenas revisiones de código son igualmente explícitas cuando solicitan un seguimiento, utilizando la herramienta de revisión de código o la convención del equipo para comunicarlo.
Las mejores revisiones de código son firmes en el principio pero flexibles en la práctica: a veces, ciertos comentarios son abordados por el autor con un cambio de código separado y de seguimiento. Para los cambios que son más urgentes que otros, los revisores intentan estar disponibles para revisiones más rápidas.
De las revisiones de código a hablar entre ellos
Las revisiones de código suelen hacerse de forma asíncrona y por escrito a través de una herramienta de revisión de código. Esto suele ser por comodidad, para permitir revisiones de código remotas y para que varias personas puedan revisar el mismo cambio de código. Pero, ¿cuándo es el momento de dejar de usar la herramienta -por muy buena que sea- y empezar a hablar cara a cara sobre el código?
Las buenas revisiones de código dejan tantos comentarios y preguntas como sean necesarios. Si la revisión no las aborda todas, también las anotarán. Cuando la conversación se convierte en un largo ida y vuelta, los revisores tratarán de hablar con el autor en persona en lugar de perder más tiempo utilizando la herramienta de revisión de código.
Las mejores revisiones de código se pondrán en contacto de forma proactiva con la persona que realiza el cambio después de hacer una primera pasada en el código y tener muchos comentarios y preguntas. Estas personas han aprendido que ahorran mucho tiempo, malentendidos y resentimientos de esta manera. El hecho de que haya muchos comentarios en el código indica que es probable que haya algún malentendido por ambas partes. Este tipo de malentendidos son más fáciles de identificar y resolver hablando las cosas.
Nitpicks
Los nitpicks son comentarios sin importancia, donde el código podría ser fusionado sin siquiera abordarlos. Pueden ser cosas como que las declaraciones de variables estén en orden alfabético, que las pruebas unitarias sigan una determinada estructura, o que los paréntesis estén en la misma línea.
Las buenas revisiones de código dejan claro cuándo los cambios son nitpicks sin importancia. Suelen marcar los comentarios de este tipo de forma distintiva, añadiendo el prefijo «nit:». Un número excesivo de estos comentarios puede resultar frustrante y desviar la atención de las partes más importantes de la revisión, por lo que los revisores procuran no excederse con estos comentarios.
Las mejores revisiones de código se dan cuenta de que un número excesivo de comentarios de error es un signo de falta de herramientas o de falta de estándares. Los revisores que se encuentran con esto frecuentemente buscarán la solución a este problema fuera del proceso de revisión de código. Por ejemplo, muchos de los comentarios más comunes de nitpick pueden ser resueltos a través de linting automatizado. Los que no se pueden resolver por lo general por el equipo de acuerdo a ciertas normas y siguiendo ellos, tal vez incluso la automatización de ellos, con el tiempo.
Revisiones de código para los nuevos miembros
Comenzar en una nueva empresa es abrumador para la mayoría de la gente. El código base es nuevo, el estilo de programación es diferente al anterior, y la gente revisa su código de manera muy diferente. Por lo tanto, ¿deberían las revisiones de código ser más suaves para los nuevos principiantes, para que se acostumbren al nuevo entorno, o deberían mantener el listón tan alto como para todos los demás?
Las buenas revisiones de código utilizan el mismo listón de calidad y el mismo enfoque para todos, independientemente de su cargo, nivel o fecha de incorporación a la empresa. Siguiendo lo anterior, las revisiones de código tienen un tono amable, solicitan cambios cuando son necesarios y se acercan a hablar con los revisores cuando tienen muchos comentarios.
Las mejores revisiones de código prestan una atención adicional para que las primeras revisiones de los nuevos miembros sean una gran experiencia. Los revisores son comprensivos con el hecho de que el recién incorporado puede no conocer todas las directrices de codificación y puede no estar familiarizado con partes del código. Estas revisiones hacen un esfuerzo adicional para explicar enfoques alternativos y señalar guías. También tienen un tono muy positivo, celebrando los primeros cambios en el código base que el autor está sugiriendo.
Revisiones entre oficinas y zonas horarias
Las revisiones de código se vuelven más difíciles cuando los revisores no están en la misma ubicación. Son especialmente desafiantes cuando los revisores están sentados en zonas horarias muy diferentes. He tenido mi parte justa de estas revisiones a lo largo de los años, modificando código propiedad de equipos en los EE.UU. y Asia, mientras que se basa en Europa.
Las buenas revisiones de código tienen en cuenta la diferencia de zona horaria cuando pueden. Los revisores intentan revisar el código en las horas de trabajo que se solapan entre las oficinas. En el caso de las revisiones con muchos comentarios, los revisores se ofrecerán a chatear directamente o a hacer una videollamada para hablar de los cambios.
Las mejores revisiones de código se dan cuenta cuando las revisiones de código se encuentran repetidamente con problemas de zona horaria y buscan una solución sistémica, fuera del marco de la revisión de código. Digamos que un equipo de Europa está cambiando con frecuencia un servicio que desencadena revisiones de código del propietario de este servicio con sede en Estados Unidos. La pregunta a nivel de sistema es por qué estos cambios se producen con tanta frecuencia. ¿Los cambios se realizan en la base de código correcta o debería cambiarse en otro sistema? ¿La frecuencia de los cambios será la misma o disminuirá con el tiempo? Suponiendo que los cambios se realicen en la base de código correcta y que la frecuencia no disminuya, ¿se puede romper la dependencia entre oficinas de alguna manera? Las soluciones a este tipo de problemas no suelen ser sencillas y podrían implicar la refactorización, la creación de nuevos servicios/interfaces o la mejora de las herramientas. Pero resolver dependencias como esta hará la vida de ambos equipos más fácil y su progreso más eficiente a largo plazo, lo que significa que el retorno de la inversión es a menudo bastante impresionante.
Apoyo organizativo
La forma en que las empresas y sus organizaciones de ingeniería abordan las revisiones de código es un gran elemento de lo eficientes que pueden ser. Las organizaciones que las consideran poco importantes y triviales acaban invirtiendo poco en facilitar las revisiones. En culturas como esta, podría ser tentador simplemente eliminar las revisiones de código por completo. Los ingenieros que abogan por hacer mejores revisiones de código pueden sentirse aislados, sin apoyo de arriba y finalmente se rinden. El resultado es una organización en la que los problemas se repiten y se acumulan.
Las organizaciones con buenas revisiones de código se aseguran de que todos los ingenieros participen en el proceso de revisión del código, incluso aquellos que puedan estar trabajando en proyectos en solitario. Animan a elevar el listón de la calidad, y los equipos facilitan discusiones saludables sobre los enfoques de revisión de código tanto a nivel de equipo como de organización. Estas empresas suelen tener guías de revisión de código para bases de código más grandes que los ingenieros iniciaron y escribieron. Este tipo de organizaciones reconocen que las revisiones de código ocupan una buena parte del tiempo de los ingenieros. Muchas de estas empresas añadirán revisiones de código como expectativas a las competencias del trabajo del desarrollador, esperando que los ingenieros senior pasen una gran parte de su tiempo revisando el código de otros.
Las organizaciones con mejores revisiones de código tienen reglas estrictas sobre que ningún código llegue a producción sin una revisión de código, al igual que los cambios en la lógica del negocio no llegan a producción sin pruebas automatizadas. Estas organizaciones han aprendido que el coste de tomar atajos no merece la pena; en su lugar, tienen procesos para acelerar las revisiones en casos urgentes. Estas organizaciones invierten en la productividad de los desarrolladores, incluyendo el trabajo continuo para desarrollar revisiones de código más eficientes y mejoras en las herramientas. Los ejecutivos de ingeniería no necesitan ser convencidos de los beneficios de las revisiones de código y otras mejores prácticas de ingeniería. En cambio, apoyan las iniciativas sobre mejores herramientas o procesos de revisión de código más eficientes que provienen de los equipos.
Cuando las personas se encuentran con revisiones que se sienten hostiles, sienten que pueden hablar y tener apoyo en todo momento para resolver el problema. Los ingenieros y gerentes senior consideran que las revisiones de código que no están a la altura son un problema tan importante como el código descuidado o el mal comportamiento. Tanto los ingenieros como los directores de ingeniería se sienten capacitados para mejorar la forma en que se realizan las revisiones de código.
Empieza con lo bueno, hazlo mejor
Las buenas revisiones de código ya tienen mucho esfuerzo. Hacen una revisión exhaustiva del cambio en sí, evitan ser opinantes con el tono de los comentarios, y dejan claros los nitpicks. Mantienen un listón consistente, independientemente de quién solicite la revisión, y tratan de hacer menos dolorosas las revisiones entre zonas horarias prestando una atención adicional a éstas. Las organizaciones que tienen buenas revisiones se aseguran de que todos los desarrolladores reciban y hagan revisiones de código con regularidad. Esto ya es un listón muy alto, pero si llega hasta aquí, no se detenga. Las revisiones de código son una de las mejores maneras de mejorar tus habilidades, ser mentor de otros y aprender a ser un comunicador más eficiente.
Llega a mejores revisiones de código mejorando continuamente en los detalles, pero también empieza a ver los cambios a alto nivel también. Sea empático en el tono de los comentarios y piense en formas fuera del proceso de revisión de código para eliminar las frecuentes críticas. Haga que las revisiones de código sean especialmente acogedoras para los nuevos y busque soluciones sistémicas para las dolorosas revisiones entre zonas horarias. Las organizaciones que tienen visión de futuro fomentan la inversión en herramientas y mejoras de procesos para mejorar las revisiones de código, cosechando más beneficios.
—
Gergely es actualmente un líder de ingeniería en Ámsterdam. Este artículo apareció originalmente en el blog de Gergely, The Pragmatic Engineer. Si quieres leer más de Gergely, puedes suscribirte a su boletín mensual para leer sus artículos sobre ingeniería, liderazgo tecnológico y sistemas distribuidos. Si quieres contribuir con artículos al blog de Stack Overflow, envía un correo electrónico a [email protected].
Etiquetas: boletín, revisión de código, ingeniería, desarrollo de software