Code review: métodos y he­rra­mie­n­tas para revisar código

La revisión del código es una parte integral del de­sa­rro­llo de software moderno. La revisión del código por parte de otros miembros del equipo de pro­gra­ma­ción nos ayuda a descubrir errores y mejorar la calidad del código. Se utilizan di­fe­re­n­tes he­rra­mie­n­tas, técnicas y enfoques que pre­se­n­ta­re­mos con más detalle a co­n­ti­nua­ción.

La revisión del código es una medida de garantía de calidad en el de­sa­rro­llo de software. El código fuente es el medio básico del trabajo de de­sa­rro­llo y el producto principal de la pro­gra­ma­ción. El código recién creado o mo­di­fi­ca­do se somete a una revisión del código. En este proceso, uno o varios miembros del equipo repasan el trabajo de un pro­gra­ma­dor.

Un proyecto de software incluye una base de código o “codebase”: una colección de archivos de código que, en conjunto, sirven para entregar un producto. Incluye el código real del producto, la co­n­fi­gu­ra­ción, las he­rra­mie­n­tas de de­sa­rro­llo, las pruebas y mucho más, todo mapeado en código. Todo el código base se gestiona con un sistema de control de versiones como Git. Se pueden gestionar varias versiones del código base en paralelo a través de varias “ramas”, por lo que permite avanzar en el de­sa­rro­llo de nuevas fu­n­cio­na­li­da­des sin cambiar la versión de pro­du­c­ción del código base.

El trabajo de de­sa­rro­llo suele tener lugar en las llamadas “Feature-Branch”, ramas que de­sa­rro­llan ca­ra­c­te­rí­s­ti­cas concretas y se integran pe­rió­di­ca­me­n­te en la rama principal. La revisión del código se realiza antes de la “fusión”, es decir, antes de que el código nuevo o mo­di­fi­ca­do se fusione con la base de código existente. El objetivo es detectar y eliminar los errores en una fase temprana antes de que el código pase a pro­du­c­ción.

Pero la eli­mi­na­ción de errores no es el único beneficio de la revisión del código. Que el código funcione, es decir, que se ejecute sin errores y logre el resultado deseado, es solo un requisito básico. Además, hay una multitud de otros criterios de calidad para escribir código limpio o clean code. La presencia de co­me­n­ta­rios, la claridad y co­he­re­n­cia del código, el cu­m­pli­mie­n­to de las di­re­c­tri­ces de estilo y que se integre co­rre­c­ta­me­n­te en los sistemas exi­s­te­n­tes son aspectos críticos que se tienen en cuenta durante la revisión del código.

Dado que la mayor parte del trabajo de de­sa­rro­llo se realiza en grupo, los efectos de la revisión del código van más allá de la pura calidad del mismo. Esto se debe a que la revisión del código la realizan otros miembros del equipo de de­sa­rro­llo y genera efectos sociales: los nuevos miembros del equipo reciben in­fo­r­ma­ción sobre co­n­ve­n­cio­nes y mejores prácticas, y el co­no­ci­mie­n­to se in­te­r­ca­m­bia y di­s­tri­bu­ye dentro de la or­ga­ni­za­ción. De este modo, la revisión del código co­n­tri­bu­ye a fomentar una cultura de la calidad.

Aunque la revisión del código la realizan personas, hoy en día estos procesos suelen estar apoyados por las llamadas “code review tools”, he­rra­mie­n­tas es­pe­cia­les de revisión del código que crean efi­cie­n­cia y liberan a las personas im­pli­ca­das de la minuciosa coor­di­na­ción de procesos, que requiere mucho tiempo. Esto permite que la gente se concentre en la revisión real del código.

Co­n­ce­p­tua­l­me­n­te, la revisión humana del código se encuentra entre dos métodos de análisis au­to­ma­ti­za­dos, el análisis estático y el dinámico. Estas son las di­fe­re­n­cias a simple vista:

El concepto de revisión del código es sencillo: uno o varios miembros del equipo de de­sa­rro­llo (llamados revisores o "reviewers") co­m­prue­ban la co­rre­c­ción del código mo­di­fi­ca­do o recién escrito. Los revisores leen el código e ide­n­ti­fi­can posibles errores y de­s­via­cio­nes de las co­n­ve­n­cio­nes es­ta­ble­ci­das en el equipo. Los revisores mejoran el código a po­s­te­rio­ri o tra­n­s­mi­ten sus co­n­clu­sio­nes a los autores ori­gi­na­les que in­co­r­po­ran los cambios.

Aunque la idea es sencilla, en la práctica, el esfuerzo de los procesos de revisión del código aumenta rá­pi­da­me­n­te y las pequeñas cosas se vuelven co­m­pli­ca­das: ¿qué cambios van juntos y cómo se comunican a los revisores? ¿Cómo se asignan los errores y co­me­n­ta­rios en­co­n­tra­dos a los lugares apro­pia­dos del código y se ponen a di­s­po­si­ción de los re­s­po­n­sa­bles de la mejora? Sin he­rra­mie­n­tas es­pe­cia­les de revisión de código, esto solo puede coor­di­nar­se en equipos muy pequeños.

En los equipos de pro­gra­ma­ción ágiles y di­s­tri­bui­dos, la revisión del código suele ser una parte integral del proceso de de­sa­rro­llo. En el contexto de la in­te­gra­ción continua, llamada en inglés “co­n­ti­nuous-in­te­gra­tion” o CI, el código se escribe, se prueba y se mantiene co­n­ti­nua­me­n­te en la base de código existente. La revisión del código por parte de una persona forma parte de la cadena de pro­du­c­ción au­to­ma­ti­za­da por la que pasa cada unidad de código. El código se integra y po­s­te­rio­r­me­n­te se traslada a los sistemas de pro­du­c­ción, solo si se superan todas las pruebas.

Echemos un vistazo a los pasos in­di­vi­dua­les de un canal de in­te­gra­ción continua o “pipeline de CI” y la posición que la revisión de código tiene en ella:

1. Escribir el código
   1. Escribir código en la Feature-Branch
   2. Probar el código en el entorno local
       
2. Integrar el código en la base de código
   1. Analizar y formatear au­to­má­ti­ca­me­n­te el código en la rama de ca­ra­c­te­rí­s­ti­cas
   2. Realizar la revisión del código e in­co­r­po­rar mejoras
   3. Combinar el código en la rama principal o “main”
   4. Re­pro­du­cir y probar la rama principal en área de pruebas o staging
       
3. Poner el código en pro­du­c­ción
   1. Combinar el código en la rama auxiliar completa o de release
   2. Re­pro­du­cir la rama de release en “live-site”

La revisión del código es una parte im­po­r­ta­n­te del control de calidad en el de­sa­rro­llo de software, garantiza que el código recién escrito esté lo más libre de errores posible y cumpla con los es­tá­n­da­res de calidad de la or­ga­ni­za­ción. A largo plazo, esto minimiza deuda técnica; a corto plazo, evita que se ejecute código de­fe­c­tuo­so en los sistemas de pro­du­c­ción.

El código es un medio poderoso; una vez escrito, el mismo código se ejecuta una y otra vez o si­mu­l­tá­nea­me­n­te como múltiples in­s­ta­n­cias. Así, los errores provocan un “efecto dominó”, en el que pequeños errores en un punto central tienen un gran impacto en todo el sistema. Suele ser mucho más costoso corregir los errores en el código que ya se está eje­cu­ta­n­do en el sistema de pro­du­c­ción que co­rre­gi­r­los de antemano.

La revisión del código ayuda a igualar las di­fe­re­n­cias de calidad entre las distintas partes de la base de código. Esto se debe a que la calidad del código varía mucho en función de las ci­r­cu­n­s­ta­n­cias en las que se escribió el código. Estos factores di­s­mi­nu­yen la calidad del de­sa­rro­llo del código de un pro­gra­ma­dor:

• Falta de ex­pe­rie­n­cia en pro­gra­ma­ción
• Poco co­no­ci­mie­n­to del sistema
• Falta de fa­mi­lia­ri­dad con las co­n­ve­n­cio­nes del equipo
• Estrés durante el de­sa­rro­llo
• De­sa­rro­llo bajo presión de tiempo
• Ago­ta­mie­n­to mental

Hoy en día, el uso del código va más allá de la escritura de programas. El código es un medio expresivo que puede uti­li­zar­se para describir con precisión todo tipo de sistemas. Por ejemplo, el código se utiliza para realizar contratos in­te­li­ge­n­tes basados en la cadena de bloques o para definir entornos en la nube a través de la in­frae­s­tru­c­tu­ra como código. Para estos enfoques también puede entrar en juego una revisión del código.

Las “best practices” pre­se­n­ta­das aquí provienen de un amplio estudio empírico de un equipo de pro­gra­ma­ción de Cisco realizado por Smart Bear. En parte, las “best practices” tienen en cuenta las li­mi­ta­cio­nes de los revisores humanos. El código es un medio complejo que requiere mucha atención para su revisión. El ser humano tiene una capacidad mental limitada que se agota con el esfuerzo continuo y, si no prestamos atención, pasamos por alto errores con facilidad y perdemos tiempo dedicado a la revisión del código.

Además, las “best practices” buscan ga­ra­n­ti­zar que los procesos de revisión del código estén orie­n­ta­dos a los objetivos. Si en­co­n­tra­mos errores, también tenemos que co­rre­gi­r­los. Esto requiere re­s­po­n­sa­bi­li­da­des claras y formas de gestionar los procesos y su­pe­r­vi­sar el progreso. Veamos las “best practices” que hemos en­co­n­tra­do:

• Comprobar un máximo de 400 líneas de código por sesión: con grandes ca­n­ti­da­des de código, pasamos por alto errores fá­ci­l­me­n­te.
   
• En caso de re­vi­sio­nes rápidas, limitarse a menos de 500 líneas de código por hora: de lo contrario, la capacidad de los revisores para detectar errores se resiente.
   
• Limitar las re­vi­sio­nes de código a un máximo de 60 minutos: con las re­vi­sio­nes de código más largas, los revisores pierden la co­n­ce­n­tra­ción necesaria.
   
• Es­ta­ble­cer objetivos y co­n­ta­bi­li­zar eventos: ¿cuántos errores se en­cue­n­tran por unidad de tiempo o por línea de código?
   
• Los autores del código deben anotar el código fuente antes de la revisión: las ano­ta­cio­nes guían a los revisores a través de los cambios en el código, y los explican.
   
• Utilizar listas de control: estas deben contener los puntos que se observan durante cada revisión.
   
• Es­ta­ble­cer un proceso para corregir los errores que se en­cue­n­tren: no basta con detectar los errores. Para corregir los errores, se necesitan di­re­c­tri­ces y es­tru­c­tu­ras claras.
   
• Promover una cultura positiva de revisión del código: los errores no deben pre­se­n­tar­se como un fallo personal, sino como una opo­r­tu­ni­dad para aprender.
   
• Utilizar las im­pli­ca­cio­nes su­b­co­n­s­cie­n­tes del proceso de revisión: si se sabe que el código está sujeto a revisión, los pro­gra­ma­do­res se esfuerzan más.
   
• Apoyarse en procesos de revisión de código ligeros: las he­rra­mie­n­tas modernas de revisión del código han hecho que la revisión del código sea eficiente.

En general, la revisión del código se considera una parte esencial del de­sa­rro­llo de software. Y es que las ventajas de estos procesos son evidentes. Sin embargo, también hay algunas de­s­ve­n­ta­jas derivadas de su uso. Veamos las ventajas e in­co­n­ve­nie­n­tes de la revisión del código.

La principal ventaja de la revisión del código es detectar y corregir los errores con an­te­la­ción, antes de que causen co­n­se­cue­n­cias negativas. Esto es mucho más eficaz que detectar y corregir los errores en un momento posterior del ciclo de vida del código. Si el código de­fe­c­tuo­so ya forma parte de un sistema de pro­du­c­ción, otros co­m­po­ne­n­tes pueden basarse en él, di­fi­cu­l­ta­n­do las mejoras.

Pero los be­ne­fi­cios de las re­vi­sio­nes pe­rió­di­cas del código van más allá de la búsqueda de errores in­di­vi­dua­les. En pa­r­ti­cu­lar, también es im­po­r­ta­n­te observar el proyecto en su conjunto: ¿cómo encaja el código en la base de código? Las re­vi­sio­nes continuas del código ayudan a ide­n­ti­fi­car patrones generales y a es­ta­ble­cer normas. Además de los errores fu­n­cio­na­les, se ide­n­ti­fi­can y abordan code smells. Si es necesario, se usa la re­fa­c­to­ri­za­ción y patrones de diseño para crear ho­mo­ge­nei­dad en múltiples co­m­po­ne­n­tes.

Las re­vi­sio­nes de código in­vo­lu­cran a los miembros del equipo de pro­gra­ma­ción y fomentan el diálogo. No es de extrañar que los procesos de revisión de código es­ta­ble­ci­dos ayuden a aumentar las ha­bi­li­da­des de co­di­fi­ca­ción del equipo. Las re­vi­sio­nes de código aglutinan y di­s­tri­bu­yen el co­no­ci­mie­n­to en el equipo y mejoran las ha­bi­li­da­des de código de sus miembros.

A nivel or­ga­ni­za­ti­vo, las re­vi­sio­nes de código ayudan a es­ta­ble­cer una cultura de la calidad. Si se sabe que se está revisando el propio trabajo, la gente tiende a es­fo­r­zar­se más. Para lograr el efecto positivo, basta con someter a un tercio del código producido a una revisión del mismo.

Por supuesto, una revisión del código supone un mayor esfuerzo para la or­ga­ni­za­ción. La revisión del código cuesta tiempo e in­mo­vi­li­za al personal, y se necesitan recursos para gestionar los procesos im­pli­ca­dos. Sin embargo, los costes in­cu­rri­dos sirven para aumentar la calidad del código. No hay que olvidar que la mala calidad del código provoca costes co­n­si­de­ra­bles.

Sin “code review tools”, es decir, sin he­rra­mie­n­tas de apoyo para la revisión del código, puede ser muy in­e­fi­cie­n­te. Esto era es­pe­cia­l­me­n­te pro­ble­má­ti­co con los métodos tra­di­cio­na­les antes de que se po­pu­la­ri­za­ra la revisión ligera del código. En cualquier caso, se necesitan metas y objetivos claros para los procesos de revisión del código. Esto hace que el esfuerzo y el beneficio sean ca­l­cu­la­bles y también evita los estados de limbo.

Por parte de los de­sa­rro­lla­do­res, las re­vi­sio­nes de código deberían suponer un aumento de los co­no­ci­mie­n­tos y de la cohesión del equipo. Para ello es im­po­r­ta­n­te promover un entorno de trabajo co­n­s­tru­c­ti­vo y re­s­pe­tuo­so. Si hay ho­s­ti­li­dad o se cu­l­pa­bi­li­za durante una revisión del código, puede tener un efecto negativo en los im­pli­ca­dos. Los recién llegados al equipo, los miembros de minorías y los pro­gra­ma­do­res re­la­ti­va­me­n­te in­e­x­pe­r­tos se ven es­pe­cia­l­me­n­te afectados por esto.

La primera forma de revisión del código se conocía como “in­s­pe­c­ción de Fagan”. Se trata de un proceso complejo que requiere cuatro personas e implica la impresión del código en papel, además de varias reuniones. Aunque es eficaz para encontrar errores, la in­s­pe­c­ción de Fagan es imposible de integrar en el trabajo de de­sa­rro­llo ágil moderno.

En contraste con la engorrosa revisión de código de Fagan, hoy en día se utilizan enfoques ligeros. En todos ellos pa­r­ti­ci­pan el autor o los autores del código y uno o varios revisores.

El método “por encima del hombro” es la forma más sencilla de revisión del código. El autor presenta el código escrito a otro miembro del equipo de de­sa­rro­llo (revisor). Además de buscar errores, se discuten las es­tru­c­tu­ras del código y se explican enfoques al­te­r­na­ti­vos. La co­mu­ni­ca­ción directa entre el pre­se­n­ta­dor y el revisor permite una re­tro­ali­me­n­ta­ción rápida y la in­co­r­po­ra­ción inmediata de mejoras.

La revisión del código “por encima del hombro” tiene lugar en el propio ordenador. Quien revisa mira el código por encima del hombro mientras quien lo escribió hace la pre­se­n­ta­ción. Esto permite el uso de todos los recursos y he­rra­mie­n­tas en la máquina de de­sa­rro­llo. Una revisión del código “por encima del hombro” no es co­m­pli­ca­da y puede rea­li­zar­se de forma puntual.

Co­n­ce­p­tua­l­me­n­te similar a la revisión de código “por encima del hombro” es la revisión de código por pair pro­gra­m­mi­ng. Una vez más, dos miembros del equipo de pro­gra­ma­ción están in­vo­lu­cra­dos. La di­fe­re­n­cia radica en cuándo tienen lugar los procesos de creación y revisión del código. Mientras que la revisión del código “por encima del hombro” tiene lugar después de la creación del código, en el pair pro­gra­m­mi­ng ambos procesos están en­tre­la­za­dos.

Durante el pair pro­gra­m­mi­ng, una persona, conocida como co­n­tro­la­dor o “Driver”, escribe el código y se encarga de los detalles de la im­ple­me­n­ta­ción. La otra persona, conocida como el navegador o “Reviewer”, supervisa el código escrito y pro­po­r­cio­na co­me­n­ta­rios. El navegador también tiene en cuenta el proyecto en su conjunto; el código no solo debe estar libre de errores y funcionar por sí mismo, sino que también debe seguir los patrones y reglas de todo el código in­vo­lu­cra­do.

Es im­po­r­ta­n­te que el co­n­tro­la­dor y el navegador in­te­r­ca­m­bien re­gu­la­r­me­n­te sus papeles. De este modo, se produce una al­te­r­na­n­cia de pe­r­s­pe­c­ti­vas, que equilibra la balanza de poder y da a ambas personas la opo­r­tu­ni­dad de re­cu­pe­rar­se me­n­ta­l­me­n­te. Además, el pa­r­ti­ci­pa­n­te con menos ex­pe­rie­n­cia tiene la opo­r­tu­ni­dad de aprender en ambos papeles.

Los cambios o nuevas adiciones de código en proyectos más grandes suelen requerir una revisión del código por parte de varias personas. La revisión del código mediante resumen por correo ele­c­tró­ni­co consiste en enviar un resumen de los cambios a todos los im­pli­ca­dos. A co­n­ti­nua­ción, se realizan varias rondas de debate por correo ele­c­tró­ni­co y se in­co­r­po­ran los cambios hasta que se completa la revisión para finalizar el código.

Como es fácil imaginar, el proceso puede volverse rá­pi­da­me­n­te confuso con un gran número de co­n­tri­bu­ye­n­tes. Por lo tanto, la revisión del código a través de rondas de correo ele­c­tró­ni­co funciona mejor con el apoyo de he­rra­mie­n­tas adecuadas.

Los enfoques modernos de la revisión del código utilizan he­rra­mie­n­tas es­pe­cia­les. Estas es­tru­c­tu­ran los procesos de revisión, aumentan la efi­cie­n­cia y recogen métricas. Las he­rra­mie­n­tas hacen que el proceso de revisión sea pla­ni­fi­ca­ble, co­n­tro­la­ble y ve­ri­fi­ca­ble.

Existe una amplia gama de he­rra­mie­n­tas de revisión de código. Algunos de ellos se integran en los enfoques exi­s­te­n­tes para la in­te­gra­ción continua o co­n­ti­nuous delivery (CI/CD). Pre­se­n­ta­mos los di­fe­re­n­tes tipos de he­rra­mie­n­tas junto con ejemplos.

Los sistemas de control de versiones di­s­tri­bui­dos (DVCS) y, en pa­r­ti­cu­lar, el om­ni­pre­se­n­te Git, co­n­s­ti­tu­yen la base de las he­rra­mie­n­tas de revisión de código. Incluyen la fu­n­cio­na­li­dad de rastrear los cambios en el código y hacerlos visibles como “diffs”. Las pla­ta­fo­r­mas co­n­s­trui­das sobre Git, como GitHub y GitLab, mejoran la vi­si­bi­li­dad y hacen hincapié en el trabajo en equipo. Con sus so­li­ci­tu­des de fusión, estas pla­ta­fo­r­mas ofrecen una revisión integrada del código antes de aceptarlo.

Estas he­rra­mie­n­tas utilizan como base Git u otro sistema de control de versiones di­s­tri­bui­dos (DVCS). A partir de ahí, se suele utilizar una interfaz de usuario basada en la web para organizar las re­vi­sio­nes del código en el equipo. Algunas he­rra­mie­n­tas de revisión de código también tienen su propia interfaz de línea de comandos (CLI).

GitHub se ha es­ta­ble­ci­do como la pla­ta­fo­r­ma estándar para la ad­mi­ni­s­tra­ción en la web de re­po­si­to­rios Git. El mecanismo principal para la revisión del código son las llamadas pull requests: si quieres hacer cambios en el código de un re­po­si­to­rio, sigue un esquema sencillo:

1. Clonar el re­po­si­to­rio como copia local
2. Realizar cambios en tu propia rama
3. Crear un pull request: pide a los ma­n­te­ne­do­res del re­po­si­to­rio que co­m­prue­ben los cambios y, si son positivos, los fusionen con el re­po­si­to­rio principal.

La he­rra­mie­n­ta de revisión de código Review Board pone en primer plano las so­li­ci­tu­des de revisión. Su moderna y amigable interfaz web pro­po­r­cio­na una visión general de todas las so­li­ci­tu­des de revisión en curso en los re­po­si­to­rios y ramas. El comando dedicado rbt permite un acceso rápido desde la línea de comandos. Además del código, también puedes incluir gráficos y do­cu­me­n­tos PDF en los procesos de revisión.

Gerrit se instala en tu servidor y actúa como interfaz entre los cambios en el código y la base de código de pro­du­c­ción. Mediante la revisión de código se su­pe­r­vi­san los cambios y solo pasan a pro­du­c­ción si son aprobados. Una in­s­ta­la­ción de Gerrit incluye un entorno Git au­to­alo­ja­do con acceso SSH y una interfaz basada en la web di­s­po­ni­ble a través de HTTPS. Además de las no­ti­fi­ca­cio­nes op­cio­na­les por correo ele­c­tró­ni­co, Gerrit incluye un sistema para votar por los cambios en el código.

La he­rra­mie­n­ta de revisión de código Code Co­lla­bo­ra­tor de Smart Bear pone en primer plano las historias o “Stories” de los usuarios. Se trata de es­pe­ci­fi­ca­cio­nes de fu­n­cio­na­li­dad centradas en el usuario que se traducen en el código y se validan mediante pruebas. La he­rra­mie­n­ta involucra al equipo de pro­gra­ma­ción, a los gestores y a los equipos de pruebas, y permite una revisión coherente de los cambios en las historias de usuario, el código y los planes de pruebas.

Estas he­rra­mie­n­tas, conocidas como “linters”, se utilizan para analizar y dar formato au­to­má­ti­ca­me­n­te al código en pre­pa­ra­ción para la revisión del mismo. Té­c­ni­ca­me­n­te, se trata de un análisis estático porque el código se lee, pero no se ejecuta. Los linters se utilizan como parte del canal CI para es­ta­n­da­ri­zar el formato del código o para adaptar el código a las es­pe­ci­fi­ca­cio­nes de estilo.

Este análisis estático también pro­po­r­cio­na métricas de código, como el número de líneas de código (LOC) por archivo, clase o función. Los linters también pueden detectar errores comunes antes de la revisión humana del código. Entre ellos se en­cue­n­tran los errores de escritura, las in­ye­c­cio­nes SQL y los errores fuera de límites.

Estas he­rra­mie­n­tas re­la­ti­va­me­n­te nuevas funcionan co­n­ce­p­tua­l­me­n­te como un editor de código basado en la web con si­n­cro­ni­za­ción de los cambios entre varios usuarios. Permiten la pro­gra­ma­ción por parejas en entornos di­s­tri­bui­dos y la revisión del código “por encima del hombro” sin importar dónde estén geo­grá­fi­ca­me­n­te los co­la­bo­ra­do­res. A raíz de la pandemia causada por COVID, estas he­rra­mie­n­tas se han hecho muy populares.

Tanto Replit como LiveShare integrado en el editor VSCode de Microsoft pueden uti­li­zar­se como editores HTML co­la­bo­ra­ti­vos. Ambas he­rra­mie­n­tas pueden manejar otros lenguajes y permiten el trabajo co­la­bo­ra­ti­vo con múltiples archivos e incluso la ejecución de código.