Code Reviews

Ricardo Vega

por Ricardo Vega el 11 de junio, 2021

Etiquetas:

Programación

8 minutos.

Hoy quiero dedicar este post a un proceso con el que seguramente estes familiarizado si te dedicas al desarrollo de código y formas parte de un equipo como es mi caso. Hoy vamos a hablar de las revisiones de código.

El proceso de revisión de código es una práctica de ingeniería que busca mejorar la calidad del código y eliminar las probabilidades de fallos en el mismo mediante la revisión por parte de una persona (o varias) que no ha participado en la codificación de una funcionalidad para detectar posibles inconsistencias y tener una segunda visión sobre el código.

Los objetivos son semejantes a los que persigue el pair-programming, pero es un proceso por norma general más asíncrono donde el revisor no entra hasta que la persona que ha desarrollado la funcionalidad la da por acabada.

Personalmente, las revisiones de código han formado parte de mi día a día prácticamente durante toda mi trayectoria profesional y actualmente suponen una de mis principales actividades. Con este post no vengo a sentar cátedra de nada sino a contar mi experiencia personal y por tanto subjetiva sobre cómo creo que podemos llevar a cabo revisiones de código de forma efectiva.

Creo que es importante empezar destacando que una revisión de código no son evaluaciones. Debemos evitar aplicar esta técnica de forma jerárquica (seniors como revisores, juniors como programadores) puesto que no persigue ser una corrección. El espíritu de una revisión de código debe ser dos personas ven más que una. Es habitual que lo que para la persona que ha codificado la funcionalidad sea evidente, no lo sea tanto para otras personas dentro del equipo o incluso para él mismo unos meses más tarde. Las revisiones de código también persiguen mejorar este aspecto, haciendo el código más limpio y comprensible. Un tono correcto en una revisión de código debe plantear cuestiones al autor del código y este debe recapacitar sobre ellas para ver si realmente puede añadir de algún modo la aportación de su compañero o explicarla mejor puesto que esa misma duda que le ha surgido a él, puede ocurrir a otra persona del equipo en el futuro. Por tanto, es también importante abandonar una actitud defensiva.

Así que mi primera recomendación es hacer partícipe a todo el mundo, pudiendo ser cualquiera revisor del código de cualquiera.

El proceso de revisión de código se articula alrededor de las Pull Requests o Merge Requests. Típicamente tienes una rama donde has llevado a cabo tu trabajo y quieres unificar esa rama con la rama principal del repositorio.

Doy por sentado que conoces los sistemas de control de versiones como GIT y sabes qué es una rama o un repositorio.

TLDR

Simplificando mucho el proceso, creo que se puede conseguir un nivel aceptable de calidad siguiendo la siguiente checklist en tus procesos de revisión:

  • El código es leíble
  • El código está testado
  • Cumple con la funcionalidad descrita
  • Los ficheros, clases, métodos siguen una nomenclatura adecuada: coherente y descriptiva
  • Los estados de error se manejan correctamente

Si queremos profundizar más en este proceso, creo que estos puntos nos pueden ayudar a hacer mejores revisiones de código:

Cuando estás haciendo una Pull Request

En primer lugar, asegúrate que tu PR es realmente necesaria. Idealmente, una PR debe ir siempre asociada a una incidencia debidamente discutida y priorizada.

Resulta importante contextualizar las Pull Requests para facilitar el trabajo del revisor. Creo que la siguiente información puede resultar de utilidad:

  • Por qué se hace la PR y, si aplicase, qué alternativas se han estudiado.
  • Debe ser pequeña, con commits pequeños y explicativos.
  • Puede demostrar los resultados con imágenes, gifs o pequeños videos.

Introduce esta información escribiendo títulos y descripciones precisas.

Especialmente en PRs que no resulten triviales, debemos crear la PR antes de acabarla, marcándola con la etiqueta "WIP" o "Draft" y añadiendo un listado de tareas por realizar. Esta costumbre nos permite tener un camino a seguir que nos pueda guiar y ayudar en el desarrollo así como permite al revisor estudiar la PR en fases de diseño (detectando problemas en etapas tempranas).

Ponte en todo momento en el punto de vista del revisor para intentar anticiparte a posibles defectos o cuestiones que él te plantee. En este sentido, es de gran utilidad que tu mismo seas el primer revisor de tu código.

Por último, y especialmente en entornos Open Source, se paciente con el revisor y todo el proceso requerido.

Cuando estas revisando el código de otra persona

Como revisor, es importante que identifiques si tus comentarios son o no bloqueantes para el mergeo de la rama. Para este propósito, frameworks como conventional comments pueden resultar útiles.

Algunos puntos que debes tener en cuenta:

  • Formateo: espaciado, saltos de linea, tabs vs espacios.
  • Naming: variables, constantes, funciones, clases... ¿están definidas correctamente? Deben ser autodescriptivas.
  • Cobertura de código: no necesariamente creo que se deba "cumplir" una cobertura concreta (excepto si es un requisito) pero unos buenos tests, aportan calidad y robustez al código.

Estas tareas pueden ser automatizadas total o parcialmente. Creo que lo mejor es delegar todo lo posible a herramientas automatizas y centrarte en otros aspectos:

Diseño

  • ¿El código encaja con la arquitectura general de la aplicación?
  • ¿Sigue los patrones y paradigmas de diseño del proyecto (SOLID, DDD, etc)?
  • ¿Qué patrones de diseño se están empleando? ¿Son correctos?
  • ¿Está el código bien estructurado?
  • ¿Se está haciendo "sobre-ingeniería? Procura seguir una filosofía YAGNI.
  • Evita optimizaciones prematuras.
  • ¿Se están usando las estructuras de datos adecuadas?

Si estás diseñando componentes, estos deben seguir el principio FIRST:

  • Focused
  • Independent
  • Reusable
  • Small
  • Testable

Si estás trabajando en una interfaz de usuario, debes tener en cuenta su rendimiento:

  • Responder a las interacciones del usuario en menos de 100ms
  • Animaciones deben dibujarse en menos de 10ms
  • Cargar en menos de 1 segundo

Mantenimiento y comprensión del código

  • ¿Los nombres (de variables, métodos, funciones, clases, etc) reflejan lo que realmente hacen o almacenan?
  • ¿Entiendo lo que el código hace simplemente leyéndolo?
  • ¿Entiendo qué hacen los tests?
  • ¿Los mensajes de error y excepciones son comprensibles?
  • ¿Las secciones más confusas están documentadas, comentadas o cubiertas por tests comprensibles (dependiendo de las preferencias del equipo)?
  • ¿Existe código sin usar o muerto?

Funcionalidad

  • ¿El código hace lo que se supone que tendría que hacer?

Otros

  • Problemas de seguridad
  • Documentación
  • ¿Están los tests suficientemente desacoplados del código?
  • ¿Rendimiento? Llamadas hacia fuera (Bases de Datos, cachés, llamadas a otros servicios) son costosas y deben ser minimizadas. Comprueba también posibles fugas de memoria (observers cerrados, promesas sin resolver, etc).
  • etc

Conclusiones e información adicional

Las revisiones de código no son la única forma de cohesionar el código que entrega un equipo intentado asegurar su calidad pero si que es una práctica muy habitual para conseguir estos objetivos sobretodo en equipos de cierto tamaño (más de 3 personas).

Como indicaba al principio, este post no es prescriptivo de nada pero si intento transmitir los aprendizajes que he tenido durante los últimos años por si pueden serte de utilidad.

Puedes encontrar numerosos recursos adicionales así como contenido crítico con este proceso como por ejemplo:

¿Qué opinas al respecto? Contacta conmigo vía Twitter para continuar con la conversación :)

Un saludo,

Ricardo

Discutir en Twitter

Compartir artículo
Ricardo Vega
Ricardo Vega es un desarrollador "full-stack" al que le gusta "cacharrear con todo" pero está especializado sobre todo en tecnologías Javascript, principalmente en React. Intenta devolver a Internet lo que Internet le ha dado.

Sigue leyendo 😀


Apoya al blog y mi actividad


Si te ha gustado este artículo, valora apoyarme económicamente a través de Patreon o comprándome un café. Cualquier pequeño donativo, significa mucho y ayuda a la continuidad del blog.

Puedes consultar otras opciones adicionales e información adicional en /donate

Permanezcamos en contacto!


¿Quieres enterarte de todas las novedades del sector? ¿Te gustaría trabajar conmigo? ¡Puedes contactar conmigo de forma muy sencilla!

@ricveal

ricardo.vega@ricveal.com

Ricardo Vega
Copyright © 2021 | Política de Privacidad