Colocalización

Esta es una traducción (libre) del artículo Colocation de Kent C. Dodds.

Con el tiempo suele ser más y más difícil manejar las dependencias (JS, CSS, imágenes, etcétera). A medida que los proyectos crecen, una mayor parte de la base de código se convierte en “conocimiento tribal” (conocimiento que sólo tú y otros pocos poseéis), y este tipo de conocimiento contribuye a la “deuda técnica” (independientemente de que el término sea preciso o no).

Mantener nuestras bases de código sostenibles no es un ejercicio sólo para nosotros mismos (quienes las escribimos), ya sea ahora o en el futuro, sino también para nuestros compañeros y otros mantenedores del proyecto. Creo que todos estaremos de acuerdo en que esto es un buen ideal que perseguir, y hay muchas herramientas y técnicas a nuestra disposición para conseguirlo.

Hablemos de comentarios de código

No quiero hablar de si deberías comentar tu código (deberías hacerlo) o sobre lo que deberías poner en tus comentarios (explica por qué estás haciendo algo inesperado para que los que vengan después puedan entender las decisiones que se tomaron). En su lugar, me gustaría centrarme en dónde se sitúan estos comentarios: generalmente “colocalizamos” los comentarios junto con el código que tratan de explicar, poniéndolos tan cerca del mismo como sea posible.

Imagina durante un minuto que lo hiciéramos de otra manera, que pusiéramos los comentarios en un fichero totalmente distinto. Tal vez un enorme fichero DOCUMENTATION.md o, mejor aún, en un directorio docs/ con la misma estructura que nuestro directorio src/. ¿Suena divertido? Para mí tampoco. Nos encontraríamos con serios problemas al no colocalizar nuestros comentarios con el código al que hacen referencia:

• Mantenibilidad: se quedarían des-sincronizados u obsoletos antes (de lo que ya lo hacen). Moveríamos o borraríamos ficheros de código sin actualizar los ficheros de comentarios correspondientes.
• Aplicabilidad: las personas mirando ficheros de código podrían perderse comentarios importantes o no documentar sus propios cambios al no darse cuenta de que existe un fichero de documentación que corresponde al fichero de código que están editando.
• Facilidad de uso: los cambios de contexto entre directorios también serían un reto con una organización como esta. Al tener que lidiar con ficheros en varios directorios, se vuelve más difícil asegurarse de que tienes todo lo que necesitas para mantener un componente.

Desde luego podríamos llegar a algún tipo de convención para este tipo de documentación, pero ¿por qué querríamos hacerlo? ¿No es más sencillo mantener los comentarios colocalizados con el código que explican?

¿Y qué?

En este punto puede que estés pensando: “Claro tío, por eso nadie hace eso de crear un directorio para comentarios y los ponen directamente en el código, es obvio. ¿A qué viene todo esto?” Todo esto viene a que los beneficios de la colocalización están en todas partes.

HTML/View

Toma el HTML como ejemplo. Todos los beneficios de colocalizar nuestros comentarios se pueden trasladar a nuestras vistas también. Antes de los frameworks modernos como React, teníamos la lógica de nuestras vistas y nuestras plantillas en sitios totalmente separados y se sufría de los mismos problemas descritos arriba. Actualmente es mucho más habitual poner estas cosas en el mismo fichero con React y con Vue, por ejemplo. Con Angular si no se encuentran en el mismo fichero, por lo menos están en ficheros contiguos (uno al lado del otro).

CSS

Otro concepto de esto aplica también al CSS. No voy a argumentar sobre los méritos del CSS-in-JS (es fantástico), pero los beneficios son de fuera de este mundo. Puedes leer más aquí.

Tests

El concepto de colocalización de ficheros aplica muy bien a los tests unitarios. ¿Cuán habitual es encontrar un proyecto con un directorio repleto de tests unitarios y que intenta replicar la estructura del código? Todos los obstáculos antes mencionados aplican también aquí. Seguramente no iría tan lejos como para poner los tests unitarios en el mismo fichero, pero tampoco descarto esta opción como una idea interesante (la implementación queda como ejercicio para el lector).

Para ayudar a conseguir una base de código más sostenible, debemos colocalizar nuestros ficheros de tests con los ficheros que testean. Esto asegura que cuando otras personas vengan al código (o yo mismo dentro de 6 meses), puedan ver inmediatamente que el módulo está testeado y utilizar estos tests como referencia para aprender sobre el módulo. Cuando se hacen cambios, la colocalización recuerda que hay que actualizar (añadir/eliminar/cambiar) los tests para que tengan en cuenta estos cambios.

Estado

El estado de la aplicación o de un componente también experimenta estos beneficios. Cuanto más alejado o desvinculado está el estado de la UI que lo utiliza, más difícil es de mantener. Colocalizar el estado tiene más beneficios que la mantenibilidad, también mejora el rendimiento de tu aplicación. Un cambio de estado en una esquina del árbol de componentes de tu aplicación va a volver a renderizar muchos menos componentes que un cambio cerca de la raíz del árbol. Colocaliza tu estado.

Ficheros de utilidades “reutilizables”

Esto aplica a los ficheros de “utilidades” y a las funciones auxiliares también. Imagina que estás escribiendo un componente y ves un pequeño trozo de código que puede ser extraído a su propia función. Lo extraes y piensas: “Uh… seguro que mucha gente podría utilizar esto”. De modo que lo sacas a otro fichero y lo sitúas en el directorio de utilidades de tu aplicación, para después seguir con tu vida.

Más tarde, tu componente es borrado, pero la utilidad que has escrito no está ni a la vista ni en la memoria de nadie, y permanece allí (junto con sus tests) porque la persona que ha borrado el componente da por hecho que se está utilizando en algún otro lugar. En el transcurso de los años, los ingenieros se esfuerzan para garantizar que la función y sus tests funcionan correctamente sin ni si quiera darse cuenta de que ya no hace falta. Se pierde tiempo y esfuerzo.

Si, en cambio, hubieses dejado la función directamente en el fichero en que se utilizaba, la historia sería totalmente distinta. No quiero decir que no prepares tests para tus utilidades complejas (por favor, hazlo), pero mantenlas cerca de donde son necesarias ayuda a evitar problemas.

Y por el amor del cielo, por favor QUITA ESTA REGLA DE ESLINT y todas las que se le parezcan.

El principio

El concepto de colocalización puede reducirse al siguiente principio fundamental:

Sitúa el código tan cerca como sea posible de donde es relevante.

También puedes decir: “Las cosas que cambian juntas deberían estar localizadas tan cerca como sea razonable”. (Dan Abramov dijo algo parecido a Kent C. Dodds en una ocasión).

Haciendo el open source (más) fácil

Además de evitar los problemas expuestos anteriormente, hay otros beneficios en estructurar tu código de esta manera. Convertir un componente en un proyecto open source es tan sencillo como copiar y pegar su carpeta y publicarlo en npm. Entonces simplemente lo instalas en tu proyecto, actualizas la manera de importarlo, y listo.

Excepciones

Seguro que hay argumentos sobre documentación que comprende todo o una buena parte de un sistema y cómo las cosas se integran entre sí. Y, ¿dónde pondrías tus tests end-to-end (E2E) o de integración que abarcan varios componentes? Puedes pensar que estas son excepciones, pero en realidad pueden adherirse muy bien al principio mencionado arriba.

Si tengo una parte de mi aplicación asociada con la autenticación de usuario y quiero documentar este flujo, puedo crear un fichero README.md en la misma carpeta en la que se encuentran todos los módulos asociados con la autenticación. Si necesito escribir tests de integración para dicho flujo, puedo añadirlos en la misma carpeta.

Para los tests E2E, estos generalmente tiene más sentido que vayan en la raíz del proyecto. Abarcan más allá del proyecto en sí y hasta otras partes del sistema, así que tiene sentido que dichos tests estén en un directorio separado. No guardan relación directa con los ficheros de código. De hecho, a los tests E2E no les importa en absoluto cómo organizas tu código. Refactorizar o cambiar ficheros de sitio dentro de las carpetas de código no debería necesitar ningún cambio en los tests E2E.

Conclusión

Nuestro objetivo es construir software que sea tan sencillo de mantener como sea posible. Los mismos beneficios de mantenibilidad, aplicabilidad y facilidad de uso que obtenemos de colocalizar nuestros comentarios los obtenemos también de colocalizar otras cosas. Si nunca lo has intentado, te recomiendo que le des una oportunidad.

P.D: Si estás preocupado sobre el principio de “separación de responsabilidades”, te recomiendo que veas esta charla de Pete Hunt y revalúes lo que significa.

P.P.D: Debo mencionar que todo esto también aplica a imágenes y otros recursos, y cuando utilizas una herramienta como webpack, colocalizar estos recursos es extremadamente fácil. Sinceramente, creo que esta es una de las principales propuestas de valor de webpack.