El cuarto de trebejos y la documentación

En la casa tengo un cuarto de servicio que mi hermano y yo usábamos como taller cuando hacíamos alebrijes, pinturas en óleo y cosas así. Lo llamábamos cariñosamente “el cuartito” y el nombre llegó a ser conocido en un par de exposiciones. Mi hermano se fue a vivir a Pachuca y yo comencé a hacer software y los dos dejamos de hacer “manualidades”, dejando aquel cuarto un poco en el olvido, con el tiempo, fue acumulando polvo y basura que ambos llevábamos usándolo como cuarto de trebejos.

Hoy decidí entrar al “cuartito” y darle una arreglada para volverlo a poner en funcionamiento, más a modo de hobby que pensando en dejar el desarrollo de software, y lo que encontré fue algo verdaderamente de miedo, las lluvias y una ventana abierta invitaron a la humedad a destrozar casi todos los papeles que teníamos, los otros se echaron a perder con el sol. Las pinturas estaban secas, el polvo y los trebejos hacían difícil respirar y en resumen, el lugar era un verdadero asco.

Después de cuatro costales de basura: papeles enmohecidos, pedazos de unicel, lienzos desgarrados y otro montón de porquerías, el lugar empezó a tomar forma nuevamente. Actualizarlo y ponerlo a andar requerirá un par de días más de limpieza, comprar nuevas pinturas y otros materiales, darle una pintadita y por supuesto, volverlo a utilizar.

Cuando terminaba esta primera sesión de restauración me pareció que la suerte de este “cuartito” era muy similar a la de la documentación en el software.

Como promotor de la metodología XP creo que la documentación debe estar en el código, pero esta creencia no es nomás porque así lo dijo Beck, sino por evitar el fenómeno del “cuartito” en la documentación.

Cuando la documentación se crea, está basada en el código, la arquitectura, los requerimientos y el modelo de dominio que se tiene en ese preciso momento, pero mientras el proyecto avanza, el modelo de dominio evoluciona, los requerimientos se refinan o cambian, la arquitectura se adapta al modelo y el código se transforma para reflejar todo lo anterior, sin embargo, a menos que uno sea un ejemplo de disciplina, la documentación comienza a atrasarse, poco a poco se le usa menos (los desarrolladores muchas veces creen que la documentación o es para el cliente o es para un futuro muy lejano) y el polvo y el tiempo se apoderan de ella. Al final del proyecto, la documentación o bien se rehace como estoy haciendo con el “cuartito” o bien se deja como está sabiendo que nadie la usará.

Por esta razón, considerar el código mismo como documentación es una manera de vacunarnos contra este abandono, el código sí cambia, reflejando los cambios en todo lo demás.

Pero pretender que el código completo sea su propia documentación es llegar un poco demasiado lejos y pecar cuando menos de ingenuidad. Incluso con la mejor intención, habrá veces que el nombre de un miembro no sea del todo correcto para lo que hace o expone, o quizá el nombre era correcto, pero un cambio de funcionamiento lo llevó a desactualizarse (en este sentido, la documentación en comentarios del código, o la confianza en la buena nomenclatura de miembros puede sufrir del mismo síndrome del “cuartito”).

La mejor opción para código documentador son las pruebas unitarias, primero por que la metodología XP exige que no se escriba código sin probar, segundo porque cualquier refactoring debe estar respaldado por pruebas y debe cumplir con todas las demás. Las pruebas siempre están actualizadas, son un reflejo confiable del código, un metacódigo que nos dice cómo se relacionan, cómo funciona, qué deben hacer y cómo se usan las otras piezas del código.

Pero incluso con las pruebas hay cosas difíciles de ser documentadas por código. Aquí es donde mi afición por la XP cierra los ojos y me deja documentar por escrito y en lenguaje natural en un procesador de texto.

El modelo de dominio puede ser representado de una manera muy eficiente por el mismo código, sin embargo, la explicación de ciertas relaciones o la definición de ciertos elementos no pueden ser llevadas al código. Hay cosas en el modelo de dominio que tienen que ver con cómo entienden los expertos las cosas, ese entendimiento tiene que ver con cómo se ha pensado el modelo, y por tanto, justifica la arquitectura y repercute en el código, pero sin documentación no habrá registro de él y se perderá en el olvido, a pesar de ser la justificación de muchas cosas en el sistema y su implementación.

Así pues, creo que el modelo de dominio es una de esas cosas que sí deben ser documentadas por fuera del código, sobre todo porque en el código no es posible documentarlas. Con la diferencia de que cualquier cambio al código no debe obligar un cambio en esta documentación, sino al contrario, cuando esta documentación cambia significa que el código también cambiará.

En este sentido, el modelo de dominio y su documentación estarán a salvo del síndrome del “cuartito” siempre y cuando se entienda bien que el modelo de dominio no se hace en función del código, sino que el código se hace en función del modelo de dominio.

One thought on “El cuarto de trebejos y la documentación

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s