En entradas anteriores hemos explorado la forma en que un programador desarrolla su profesión. Igualmente, se ha hecho notar que una parte fundamental en dicha labor está la documentación, la cual suele dejarse de lado por considerarse inútil o una pérdida de tiempo. Sin embargo, a pesar de que se acepte de lleno el hecho de que es una necesidad el documentar, queda la duda de cómo comenzar tal labor. ¿Qué formas tiene un programador para llevar a cabo tal tarea?
Es claro que existen diversas formas en que un programador pudiera documentar su código. Una forma común de lograrlo es mediante la elaboración de un documento externo en el que se plasmen las ideas, detalles y explicaciones relativas al trabajo hecho. Esta forma, si bien la ideal en cuanto a detalle y alcance, suele ser bastante tediosa y compleja de llevar. Entre otras cosas, esta alternativa tiene las siguientes complicaciones que la vuelven una opción poco atractiva:
- Se necesita escribir un documento desde cero ajeno al proyecto.
- Tras realizar un cambio o adición al sistema, es necesario modificar el documento para actualizar su contenido.
- Es necesario elaborar diagramas diversos los cuales pueden ser tardados y complicados de elaborar.
Por razones como las anteriores, es por eso que existen diversas alternativas para intentar facilitar esta tarea. Una de estas alternativas, y de cual hablaré un poco en esta entrada, es Doxygen. Esta aplicación multiplataforma (es decir, que está disponible para usarse en los sistemas operativos más populares, Microsoft Windows, GNU/Linux y Apple MacOS) tiene como objetivo el permitir escribir documentación de una forma sencilla, rápida y práctica.
Parte de estas facilidades se dan por la forma en que la documentación es elaborada. Otras alternativas solicitan que el programador (u otra persona) escriba manualmente un documento externo y prepare, igualmente a mano, las imágenes y gráficos correspondientes. Sin embargo, Doxygen tiene una solución diferente. Éste define que la documentación debe de ser escrita dentro del propio código. De esta forma, Doxygen, una vez que se le indica dónde está el código del sistema programado, es capaz de leerlo, analizarlo y preparar documentación con calidad profesional. Pero, ¿cómo lo logra?
Doxygen se aprovecha de uno de los mecanismos que la mayoría de los lenguajes de programación provee a los programadores, el cual es el de los comentarios. Un comentario es texto que se escribe junto al código, el cual se usa para permitir a los programadores hacer descripciones del código mismo. De esta forma, Doxygen solicita que se escriban comentarios con cierto formato, de tal forma que éstos sean identificados por sobre otros comentarios y el código. Así mismo, al colocarse en puntos definidos (antes, a un lado o después de ciertos componentes que un lenguaje define), Doxygen es capaz de darles un contexto en el código que acompaña.
Sin embargo, Doxygen no hace sólo una tarea de recopilación de comentarios. Como parte de sus actividades, Doxygen genera, automáticamente, gráficos y diagramas del proyecto analizado. Todo este texto recopilado, gráficos, diagramas y datos variados extraídos del proyecto, son plasmados dentro de documentación con calidad profesional, la cual puede ser generada en diversos formatos (HTML para ser visto en una página web, PDF para ser distribuido o impreso, entre otros).
De esta forma, Doxygen permite a los desarrolladores trabajar con más libertad al permitirles olvidarse de crear documentación tal cual, centrándose en sus actividades, invirtiendo solamente una cantidad mínima de tiempo en agregar comentarios que, muy seguramente, habrían agregado desde un inicio, siendo solo necesario seguir algunas reglas muy simples.
Por tanto, como conclusión, podemos definir que Doxygen, si bien no es la única opción disponible para facilitar la tarea de un programador al momento de elaborar documentación, si es una de las más populares y una que personalmente recomendaría a todo aquel desarrollador que buscara mi consejo.
En este enlace, el lector podrá encontrar la página principal de Doxygen, donde encontrará información detallada sobre esta aplicación.
