La importancia de la documentación en la programación

180

En entradas previas hemos explorado la profesión de la programación y la importancia de ésta para otras áreas laborales. En esta entrada expondré una situación recurrente en nuestra profesión que acumula dolores de cabeza y se convierte en no menos que un problema de cultura a nivel profesional y empresarial dentro de grandes, medianas y pequeñas empresas por igual.

En la programación, uno de los principales productos elaborados no es otro sino código. Éste, siendo el texto que representa las ideas y soluciones planteadas por un programador, no son fáciles de interpretar en grandes cantidades si no se conoce previamente el contexto bajo el cual fue elaborado y la solución que se intentó implementar.

Una situación recurrente en empresas, es la entrada de un elemento nuevo, un nuevo empleado que tiene como tarea inicial el leer, escudriñar y entender cantidades considerables de código. Para esta tarea, varios empleadores se centran en la filosofía “si puedes leerlo, puedes entenderlo todo”, lo cual es incorrecto desde mi punto de vista.

Si bien es cierto que un programador es capaz de ver un código e indicar claramente qué está haciendo dicho código, le será complejo definir o entender el contexto en que dicho código funciona o el problema que tiene como objetivo el solucionar. ¿Cómo podría entonces un programador atacar un problema así? ¿Cómo podría un programador enfrentarse ante tal tarea de leer y comprender un código considerablemente extenso?

La industria, de acuerdo a mi experiencia, recurre a dos opciones (pudiendo existir otras no contempladas en esta entrada):

  1. Crear documentación extensa sobre el sistema que se ha desarrollado.
  2. Depender enteramente de la experiencia de aquellos empleados ya familiarizados con el sistema.

La primera opción refiere que es necesario elaborar extensos documentos que explican en gran detalle el funcionamiento del sistema, partiendo de lo general (el problema que el sistema intenta resolver) para llegar a lo particular (explicando cómo funciona cada parte del sistema, qué hace, porqué lo hace así y cómo interactúan entre sí las partes).

La idea detrás de esta opción es que el programador pueda ser introducido al sistema, desde el problema que se espera resolver, hasta niveles detallados, de forma que comprenda la razón de que se haya elaborado alguna pieza de tal o cual forma y las decisiones de diseño que se han tomado (“¿Porqué hacer 1000 sumas en lugar de una multiplicación?”, “¿Por qué leer una lista de adelante hacia atrás, y no al revés?”).

La segunda opción consiste en confiar plenamente en la memoria de aquellos empleados experimentados en el sistema, quienes, usualmente, son quienes participaron en la creación inicial del mismo, de tal forma que tienen un contexto sobre el funcionamiento de éste que los demás no tienen.

Como puede observarse, estas opciones tienen diferentes ventajas y desventajas. En el caso de la segunda opción, ésta suele ser la más socorrida, sin embargo, ésto suele ser así por diversos problemas con la cultura e ideología que varias empresas pudieran imponer en sus procesos.

El confiar plenamente en la experiencia de un programador puede aparentar tener varias ventajas:

  • Los nuevos elementos son introducidos rápidamente al sistema, y son capaces de ser productivos en poco tiempo, días o incluso horas.
  • Prácticamente no hay tiempo “desperdiciado” entre tareas, de tal forma que las correcciones, mejoras y adiciones al sistema se pueden hacer en poco tiempo.

Estas ventajas pueden ser muy atractivas para las empresas, ya que gracias a éstas es que el cliente logra obtener su producto en tiempo y “forma”.

Sin embargo, existen desventajas al momento de seguir esta tendencia o “cultura” de la no documentación que suelen ser ignoradas:

  • Uno o pocos miembros de un equipo se vuelven vitales e indispensables para el buen funcionamiento del proceso de desarrollo, ya que sin éstos y su experiencia, se vuelve complejo comprender y manejarse dentro de un sistema que pudiera ser masivo.
  • Estos miembros experimentados se vuelven “gurús” dentro de un equipo, de tal forma que son consultados constantemente sobre detalles del sistema, lo cual los aleja de sus tarea de desarrollo, por lo que “pierden” horas explicando el sistema a varios miembros del equipo, posiblemente repitiendo información varias veces.
  • En caso de que un miembro “gurú” del equipo parta (ya sea renuncia, despido o movimiento a un ambiente diferente dentro de la misma empresa), el equipo que dependía de su conocimiento puede entrar en problemas pues el funcionamiento del sistema se habrá ido con éste, así como posibles “trucos” que solo el miembro que parte conocía.

Estos problemas son de consideración y de gran impacto para una empresa, pues ésta se vuelve dependiente enteramente de ciertas personas y sus conocimientos adquiridos. Así mismo, como he logrado observar a lo largo de mis años de experiencia, los miembros que buscan el apoyo del miembro “gurú” del equipo pueden llegar a obtener una respuesta insatisfactoria o incompleta al momento de hacer preguntas sobre el sistema, dejando a su suerte a los miembros menos experimentados, llegando a algunos problemas comunes:

  • Una solución pudiera no funcionar para todos los casos en que la falla se presentaba, pues el desarrollador no conocía todos los casos en que pudiera presentarse la falla a solucionar.
  • Una adición de funcionamiento pudiera estar repitiendo código ya existente en el sistema, duplicando funcionamiento y dando pie a que un mismo problema tenga que ser resuelto en varios puntos del sistema en casos futuros.
  • Un miembro nuevo de un equipo pudiera pasar considerables cantidades de tiempo analizando manualmente el código del sistema por pena a preguntar (una situación considerablemente común, en que se ve al miembro “gurú” del equipo como una última fuente de información, no como una fuente primaria).
  • Una eliminación o modificación de funcionamiento pudiera afectar componentes no considerados dentro del propio sistema, o fuera de éste, pues no se sabía el alcance del cambio, ya sea porque el “gurú” del equipo olvidó mencionarlo, o porque pudiera haberlo olvidado enteramente.

Estos problemas son considerables. Son problemas que no deben de dejarse de lado, ni omitirse en momento alguno, ya que, entre otras cosas, pueden llevar a tener un sistema mal-hecho, de baja calidad y propenso a errores, así como que requiere grandes inversiones de tiempo y fuerza laboral para realizar pruebas completas del mismo, ya que pudiera no saberse el impacto de un cambio, forzando a probar todo el sistema.

Entonces, ¿por qué las empresas pudieran optar por este proceder? ¿Por qué en tan diversos lugares se considera que es mejor? Muy simple: Tiempo y la mala planificación.

Una empresa valora de forma significativa el tiempo que invierte en hacer algo. Es entendible y se acepta. Sin embargo, en demasiadas empresas ven como una pérdida de tiempo el documentar. Suelen considerar que invertir una determinada cantidad de horas en planear un cambio y una cantidad de horas después de éste en documentar qué se hizo es tiempo muerto o que “se puede hacer después”, siendo este después un tiempo que rara vez llega, y en caso de llegar, puede hacerlo de forma incompleta o incorrecta.

¿Qué cambios traería el documentar? La generación de documentación, bien elaborada y extensa, si, requiere de una inversión considerable de tiempo. Es cierto que es tiempo en el que no se hace “nada”, pero este “nada” puede ser usado para plasmar las ideas, las razones y las consideraciones que se tuvieron en mente antes, durante y después de realizar un cambio, adición o remoción en un sistema.

He de admitir, y me atrevo a defender, que la generación de documentación no es sencilla, no es divertida ni es rápida, ya que requiere de casi tanta inversión mental como en el planteamiento de una solución. Documentación bien elaborada no solo incluye el qué se hizo, sino el porqué.

Así, pues, ¿qué ventajas trae la documentación a un equipo? La generación de documentación trae consigo los siguientes puntos que creo importantes:

  • Se logra dejar una base firme y bien fundamentada de conocimiento, de tal forma que no sea necesario depender de la memoria de algún miembro del equipo.
  • Es posible tener una base de conocimiento que permita realizar búsquedas claras y precisas sobre diversos aspectos del sistema (“¿En donde se hacía esta operación?”, “¿qué proceso seguimos para convertir tal resultado en tal otro resultado?”).
  • Es posible visualizar el contexto en el cual un componente funciona, qué afectaciones podría haber en caso de modificarlo y, puntualmente, qué pruebas serían útiles para certificar el cambio que uno buscaría.
  • Se deja un documento formal que puede ser de utilidad para demostrar un historial de cambios, lo cual permite visualizar la evolución del sistema, las diferencias del sistema actual y el original, etc.

Estos puntos son bastante alentadores, pero por desgracia una gran porción de las empresas (grandes, pequeñas y medianas) que he logrado conocer, recaen más en el modelo del empleado “gurú” que en una que documente para un futuro. Esto se debe, entre otras cosas, al modelo de cultura que muchas empresas desean seguir, donde consideran prioritario estar “activas” desarrollando todo el tiempo, y ven el tiempo de un empleado, leyendo documentación, como tiempo perdido.

Este problema es solucionable, pero requeriría de un gran esfuerzo por parte de usted, el lector, y de nosotros, los desarrolladores, para intentar realizar el cambio y mejorar esta situación que lleva a sistemas sub-óptimos. El mayor cambio debería darse en nosotros, como empleados o empleadores, aprendiendo y entendiendo el valor de invertir tiempo en tal actividad.