Conquistando la Complejidad: Refactorización de Proyectos JavaScript

¿Qué tal a todos? Mi nombre es Phil Nash, y soy un ingeniero de relaciones con desarrolladores en Datastacks. Datastacks es una empresa detrás de AstroDB, que es una base de datos vectorial sin servidor que puedes usar para construir tus aplicaciones de IA generativa. De nuevo, mi nombre es Phil Nash. Si necesitas encontrarme en cualquier lugar de internet, seré Phil Nash, y Twitter, Mastodon, cualquier red social que estés usando en este momento, incluso LinkedIn, por Dios. De todos modos, de lo que quiero hablarles hoy es de la complejidad, la complejidad en nuestro código. Así que comencemos hablando de lo que quiero decir con complejidad. Verán, nuestros trabajos son complejos. A menudo tenemos que modelar cosas de la vida real, del mundo real en el medio de JavaScript o TypeScript o cualquier otro tipo de lenguaje. Y el mundo en sí mismo es inherentemente complejo, y luego simplemente añadimos a eso al intentar convertirlo en código. Y el código, por lo tanto, en sí mismo es inherentemente complejo.

Lo que queremos evitar es simplemente añadir más complejidad a nuestras aplicaciones de la que el problema que estamos tratando de resolver exige por sí mismo. Y, en última instancia, esto significa que nuestro trabajo se convierte en gestionar la complejidad. Mientras podamos mantenernos al tanto de esta complejidad, entonces nuestras bases de código se mantienen cuerdas, fáciles de entender y fáciles de trabajar con el tiempo y con los cambios de equipo y todo tipo de cosas así.

Así que nuestro trabajo es gestionar la complejidad. Sin embargo, el año pasado en algunas otras conferencias, di una charla en la que analicé los cinco principales problemas en proyectos de JavaScript que podrían ser descubiertos por análisis estático, y en el número dos estaba el hecho de que la complejidad de las funciones en nuestros proyectos era simplemente demasiado alta. Y eso es un problema. Por eso quería dar esta charla para superar eso. Y entonces realmente la pregunta es, ¿qué es demasiado alto? Necesitamos un método para medir nuestra complejidad en nuestro código. ¿Y cómo podríamos hacer eso? ¿Cómo medimos la complejidad?

Bueno, primero que nada, déjame, si te mostrara un fragmento de código, si te mostrara una función como esta, una suma de números primos, y te preguntara cuán compleja es, solo piensa en lo que podrías responder y cuán útil sería eso. Obviamente hay algo de complejidad aquí. Tenemos algunos bucles. Tenemos algunos condicionales. Estamos tratando con números primos. Eso va a ser complejo. Y luego tenemos esta otra función. Esta es una función de obtener palabras. Pasamos un número y devuelve palabras como uno, un par, unos pocos, muchos o un montón. Es una gran declaración switch. ¿Cuán compleja es esta? Bueno, ha habido formas de medir la complejidad que han surgido, han sido inventadas a lo largo de los años. En 1976, se inventó la complejidad ciclomática. La complejidad ciclomática otorga una puntuación a una función basada en un par de cosas. Principalmente añade puntuaciones por cuando una función tiene una interrupción en el flujo. Es decir, cuando hay un bucle o un condicional en su mayoría. Y así, si miramos nuestra función de suma de números primos, la complejidad ciclomática realmente puntúa uno por ser una función. Todo comienza como uno. Así que comienza ahí arriba. Y luego puntuamos uno por este primer bucle for. Hay un segundo bucle for que puntúa uno. Hay un condicional. Y luego hay otro condicional en la parte inferior.

Y así, en última instancia, esta función puntúa cinco. ¿Compleja? Bastante compleja. Lo averiguaremos. La función get words, sin embargo, también puntúa uno por ser una función. Y luego, como es una declaración switch, puntúa uno por cada caso en el switch. Y hay cuatro de esos casos. Así que, en última instancia, get words también se convierte en cinco. Y no estoy seguro de que estaría de acuerdo en que get words y sum of primes sean necesariamente equivalentes en complejidad. Así que quizás haya algo que podamos hacer sobre nuestra complejidad ciclomática. Sobre nuestra complejidad ciclomática que podría ser mejor.

La complejidad ciclomática es útil. Mide el número de caminos a través de una función. Y eso es realmente útil si quieres saber cuántas pruebas necesitas para cubrir esa función y todas las funcionalidades o posibles ramas. Pero realmente no cubre cómo medimos la comprensibilidad, cómo nosotros como humanos leyendo código realmente lo entendemos. Y así, las personas de Sona en 2016 idearon una puntuación llamada complejidad cognitiva. Esta es una puntuación que fue más destinada a cómo pensamos sobre el código y cómo leemos el código y lo puntuamos de esa manera. Y así, la complejidad cognitiva se puntúa de manera similar a la complejidad ciclomática. Todavía va a llegar a un número al final del día, pero esta vez incrementa la puntuación cada vez que llegas a una interrupción en el flujo. Pero también mantiene la idea de una puntuación de anidación en el fondo de su mente. Y cada vez que incrementas, incrementas uno más la puntuación de anidación actual. Y eso hace una diferencia, llega a un resultado diferente.

Y es algo interesante. Y así, si volvemos a nuestra función sum of primes, lo que vemos es que ya no tenemos que puntuar por ser una función. La puntuación mínima aquí es cero, pero puntuamos uno por este primer bucle for. Y luego incrementamos la puntuación de anidación en uno. Así que cuando llegamos al segundo bucle for puntúa dos y la puntuación de anidación se incrementa de nuevo, llegamos al condicional.

Llegamos a la siguiente condicional. Así que eso puntúa dos porque está anidado una vez. Y luego finalmente salimos por completo hasta que la puntuación final es ocho. Así que la complejidad cognitiva de la función sum of prime es ocho, pero nuestra función get words, que creo que acordamos es menos compleja anteriormente, ahora solo puntúa uno. Es una gran declaración switch. Tenemos que considerar un valor y un número de cosas que hacer con él, pero solo estamos mirando un valor a la vez. Y así puntúa uno. Y creo que eso tiene más sentido para la forma en que pensamos las cosas, la forma en que entendemos el código. Para mí, el modelo de esto era como una especie de pila de cosas en tu cerebro que tienes que considerar mientras lees fragmentos de código. Y a medida que avanzas en algo como sum of primes, terminas agregando cosas a la pila a medida que avanzas.

Y terminamos teniendo que saber y entender en todo momento que tenemos dos variables de bucle y estamos dentro de un condicional, y eso es bastante complejo. Obviamente, puedes empeorar que esto. Y luego hay algo de revolverse también mientras salimos de la pila y luego agregamos cosas de nuevo a ella. Y tenemos que seguir averiguando qué está en y fuera de nuestra pila cerebral, qué realmente tenemos que considerar en este punto durante la parte de comprensión del código. Y luego, una vez que finalmente todo sale, vamos a respirar un suspiro de alivio porque llegamos al final de la función. Pero revolverse y construir cosas en una pila cerebral como esa es el tipo de cosas que queremos evitar. Y entonces, ¿cómo conquistamos esta complejidad? Eso es lo que el resto de esta charla va a ser como vencer eso. Y el primer paso para conquistar esa complejidad es entender dónde está la complejidad. Te he dado esta puntuación de complejidad cognitiva, pero ahora tenemos que poder aplicarla realmente a nuestro código. Y así, aquí hay una demostración rápida solo para mostrar eso. Entonces, lo que hice fue que me metí en este es el cliente de código abierto AstraDB escrito en TypeScript para tratar con instancias de AstraDB. Resultó que en realidad no había nada que fuera tan complejo aquí. Así que, en realidad tuve que agregar algunas cosas. Así que elegí cuál era la función más compleja y luego agregué más cosas para empeorarla. Así que, por favor, no culpes a las otras personas que escribieron esta maravillosa biblioteca. Entonces, lo que hice fue mirar la función insert many. Y tengo en VS code aquí, tengo ejecutando Sonalint, que es lo que estaba usando para mirar la complejidad cognitiva antes. Y esto me dice que esta función tiene una complejidad de 34 sobre los 15 permitidos. Y así, ese es el tipo de umbral que Sonalint elige sobre la complejidad cognitiva.

Añadimos cosas a la pila. Y puedes ver, de hecho, si vas a, si desplazamos todo el camino hacia abajo y pulsamos corrección rápida, puedes pulsar mostrar todas las ubicaciones para esto. Y saca estos números junto al código donde está añadiendo complejidad. Así que, hay este gran tipo de condicional alrededor del exterior. Si hay documentos con los que estamos tratando, entonces continuaremos. Y eso puntúa uno. Pero luego todo lo demás se anida dentro de él. Así que, este condicional es más dos. Este condicional es más tres porque está anidado dos veces. Este es más cuatro porque también se anidó dentro de este bucle. Y así, poder ver esta complejidad es súper útil. El paso dos, entonces, es no hacer nada. Lo cual me gusta. Soy un desarrollador perezoso. Y si no tengo que hacer nada, eso es brillante. Pero el punto aquí es que no tiene sentido cambiar algo si es complejo si no necesitas realmente cambiarlo.

Esa complejidad solo es difícil para nosotros de manejar cuando tenemos que entender y cambiar ese código. La complejidad solo es un problema si necesitas cambiar el código. Y así, si hay diferentes en la base de código, hay diferentes partes que cambian más a menudo que otras. Algunas de ellas están siendo trabajadas activamente. Y eso es lo que necesitamos prestar atención. Pero en una base de código antigua, probablemente hay partes de código que nunca cambiarán. Y si son complejas, pero no tienen que cambiar, podemos dejarlas estar.

En realidad, es un riesgo cambiar el código que no necesita ser cambiado solo por la idea de que vamos a mejorarlo de alguna manera. Si ya hace el trabajo que se supone que debe hacer, entonces podemos dejarlo hasta que necesite cambiar. Y luego, si necesita cambiar, recomiendo que limpiemos ese código a medida que avanzamos. ¿Y a qué me refiero con eso? Bueno, creo que cuando encontramos que tenemos que cambiar algún código y encontramos que es demasiado complejo, esa es una buena oportunidad para refactorizar ese código primero y facilitar ese cambio en el futuro.

Así que, podemos dividir esto en dos cosas. Tenemos que cambiar el código. Tenemos que corregir un error o agregar una característica. Pero es demasiado complejo. Si lo refactorizamos primero, se vuelve más fácil cambiar para corregir ese error o para hacer esa característica una vez que esté refactorizado. Así que, refactorizar, te recuerdo, es mejorar cómo funciona una pieza de código sin cambiar lo que hace esa pieza de código. Eso significa que obtenemos el mismo resultado después de una refactorización que antes. Y eso es importante. También es importante que estemos dividiendo este tipo de cambio en dos etapas. Refactorización primero, donde lo que hace la función no cambia. Y solo cómo lo hace. Y luego, más tarde, hacemos la corrección o más tarde, agregamos la característica. Ahí es cuando realmente cambia su comportamiento.

Entonces, ¿cómo sabemos que no cambiamos el resultado de una pieza de código? Bueno, con suerte ya estás gritando a la pantalla, pruebas. Absolutamente necesitamos alguna cobertura de pruebas aquí para que podamos tener confianza de que una vez que hemos refactorizado algo, sigue haciendo lo mismo que estábamos haciendo que hacía antes. Y también es importante notar que las pruebas en este caso deben asegurar que prueban lo que hace una función y no cómo lo hace también. Si una prueba depende de la estructura interna de una pieza de una función o una pieza de código, y cambias la estructura interna, entonces esas pruebas van a fallar incluso si no rompiste lo que hace la función. Y así, las pruebas deben asegurar que prueban solo lo que hace la función y no cómo lo hace. Y así, si aún no tienes pruebas para una pieza de código que necesitas refactorizar y necesitas cambiar, entonces tu paso 0 en este proceso es escribir esas pruebas, obtener la cobertura de pruebas.

Y es importante señalar nuevamente, esas pruebas deben cubrir el comportamiento existente. Si estamos corrigiendo un error en una pieza de código, pero decidimos refactorizarlo primero, entonces esas pruebas deben cubrir todo el comportamiento existente, incluso si es incorrecto. Porque si estamos cambiando la prueba y el código al mismo tiempo, entonces no podemos saber si la refactorización funcionó. Necesitamos escribir las pruebas que aseguren que el código hace que la función asegure que hace lo mismo una vez que lo hemos refactorizado. Y solo entonces cambiamos la prueba y cambiamos el código para corregir el error. Y luego, en ese punto, podemos refactorizar.

Y así, para la última parte de la charla, quería repasar algunos pequeños consejos que nos van a ayudar a refactorizar el código frente a esta idea de complejidad y comprensibilidad. Y así, la complejidad cognitiva, bastante obviamente, como una puntuación, castiga el código anidado. Cuantas más cosas ponemos en la pila del cerebro, empujadas a la pila del cerebro, supongo, más complejas se vuelven las cosas. Y así, reducir el anidamiento va a ayudarte a lidiar con eso y simplemente sacar algunas de esas cosas de la pila del cerebro y dejarte con menos que considerar mientras lees una función.

Y así, las cosas que vamos a cubrir para esto son invertir condiciones y salir temprano, colapso estructural, extraer funciones auxiliares y solo un par de características de JavaScript que nos van a ayudar con esto también que son un poco más modernas. Y así, invertir condiciones y salir temprano. Esto se refiere a lo primero que te mostré en esa función de insertar muchos en la que dije que había esta gran condicional alrededor del exterior que está verificando que la longitud del array de documentos es mayor que cero. De lo contrario, simplemente devuelve un objeto vacío, realmente, un conteo insertado de cero. Esta gran condición alrededor de la función que luego tiene todo lo demás dentro, obviamente, aumenta ese anidamiento. Y si invertimos la condición, es decir, si la longitud del documento es cero o menos que cero, supongo, realmente no va a suceder con un array. Pero si la longitud del documento es cero, entonces podemos devolver inmediatamente nuestro tipo de objeto cero y luego descartar la idea de que esto es un problema más. La función puede entonces simplemente continuar segura en el conocimiento de que estamos tratando con una lista de documentos y eso está bien. Invertir y salir temprano simplemente, sí, saca cosas de la pila del cerebro y significa que no tenemos que considerar eso más adelante en la función. Simplemente sácalo de la pila del cerebro. Eso es con lo que voy.

El colapso estructural es algo similar. Estamos tratando de reducir el número de condicionales, especialmente los condicionales anidados, si podemos de alguna manera aplastarlos juntos. Y así, en este caso, insertar muchos en realidad puede tratar con un documento de opciones, objeto de opciones que puede tener un array de vectores, y luego va a intentar y unir esos vectores y documentos juntos. Pero si la longitud de los vectores y la longitud de los documentos no es la misma, entonces eso es un error, porque no van a ir juntos. Pero esto es como condicionales anidados aquí. Y lo que podríamos hacer es aplastar ese tipo de cosa juntos para verificar que si tenemos vectores y si los vectores no son iguales a la misma longitud que los documentos, entonces podemos lanzar un error. Y así, esto en realidad nos permite, en este caso, devolver temprano a través de un error en lugar de simplemente continuar anidando más y luego podemos dejar que el resto del código continúe. Aplastar esas cosas en un condicional nos permite, sí, considerarlo tratado mucho más rápido y simplemente sacarlo de la pila del cerebro.

Extraer métodos auxiliares, creo, es en realidad lo más útil aquí.

Extraer un método auxiliar es excelente si tienes repetición en tu código durante una función y no tienes que repetir código, puedes convertirlo en una función. Pero también creo que es realmente útil para nombrar el comportamiento. Ves en este pequeño extracto aquí, estamos mirando y diciendo, está bien, si tenemos el array de vectores en nuestro objeto de opciones, entonces vamos a iterar sobre los documentos. Y para cada documento, si hay un vector para él, entonces vamos a convertir ese documento en un documento más un vector. Pero tenemos que resolver todo eso leyendo el código. Y en realidad, si fueras a tomar la parte interna, que es decir, como, estamos convirtiendo este documento en un documento y un vector y extraer eso en una función que simplemente diga añadir vector al documento, entonces esta función auxiliar es bastante simple. Solo estamos tratando con un documento y luego tal vez un vector y de alguna manera devolvemos el documento y el vector o solo el documento. Y eso es una cantidad realmente pequeña de contexto con el que lidiar. Y luego, si volvemos a la función original, hemos nombrado ese comportamiento. El documento se convierte en un vector y un documento juntos. Y no tenemos que necesariamente profundizar en esa función para entender lo que está haciendo. Y así, lo que hemos hecho es reducir un montón de anidación, pero también hemos nombrado el comportamiento para que podamos entenderlo sin leerlo. Y luego, en la función auxiliar real, el contexto es mucho más pequeño, por lo que es más fácil entender la función en sí cuando está sola. Podemos probarla independientemente. Y podemos simplemente es más fácil también es menos compleja en sí misma. Nos permite sacar un montón de cosas de la pila del cerebro en ese caso.

Y finalmente, algunas características del lenguaje que creo que son realmente buenas para esto. Si alguna vez has lidiado con objetos anidados y profundizado para encontrar una propiedad en el está profundamente anidado, probablemente hayas escrito una de estas cadenas de object.first y object.first.second para no encontrarte con un undefined accidentalmente en el medio en algún lugar. Y un operador de encadenamiento opcional es súper útil para eso. Simplifica toda la línea de código y elimina todos esos tipos de condicionales booleanos. Realmente útil. Y en segundo lugar, si estás lidiando con, digamos, en este caso estamos tratando de asignar a chunk size ya sea algo que está en options.chunk size o un valor predeterminado en este caso. Y así estamos comprobando que options.chunk size no es null o undefined. Y si es cualquiera de esos dos, obtenemos el valor predeterminado. Y si no, podemos asignarlo a la cosa. Y eso es un lío completo de operadores condicionales y ternarios cuando realmente podríamos usar el operador de coalescencia de conocimiento que es efectivamente lo mismo que decir no null y no undefined. Y la línea superior aquí establecerá chunk size al valor predeterminado solo si options.chunk size es null o undefined. Y si lo estuvieras haciendo dentro del objeto mismo, es aún más fácil con el operador de asignación nula que dice que solo asignaremos esto a un valor predeterminado. Este es el signo de interrogación signo de interrogación igual. Solo asignaremos este valor predeterminado si chunk size en el objeto original es null o undefined. Súper útil. Realmente ajusta piezas de código en esos momentos y en este contexto. Y simplemente te ayuda a sacarlo de la pila del cerebro.

Así que, para recapitular, echamos un vistazo a qué es la complejidad. Básicamente, nuestro trabajo es básicamente código. Vimos la complejidad cognitiva como una forma de medir la complejidad. Y luego miramos conquistar la complejidad reduciendo la anidación, refactorizando primero, asegurándonos de tener cobertura de pruebas refactorizando, y luego haciendo el cambio que necesitamos hacer. Hay algunas herramientas que te ayudarán con esto. Así que, Sona cloud o Sona cube pueden escanear tu código como parte de tu pipeline CICD y detectarán cosas como este problema de complejidad cognitiva. Lo mismo que Sona lint. Eso es gratis para instalar en tu IDE y mostrará cosas como estaba demostrando antes. Y si estás usando ESLint, eso no tiene complejidad cognitiva como una puntuación. Pero puedes instalar el plugin ESLint, Sona JS, que sí lo tiene, y lo añadirá a tu ESLint también. Realmente útil. Y eso es todo el tiempo que tengo aquí.

Nuevamente, mi nombre es Phil Nash. Soy un ingeniero de relaciones con desarrolladores en Datastacks. Y muchas gracias por ver.