EMU-Code: Effective Mark-Up of Source Code

Combinación de documentación y código

Emu

Durante el desarrollo de un proyecto software es necesario generar no solamente el producto final que se distribuirá a los usuarios, sino también otros elementos software que facilitan el desarrollo y permitirán el mantenimiento futuro de la aplicación.

Entre estos elementos se encuentra la documentación que debe acompañar al código fuente para permitir su lectura y comprensión por parte de los desarrolladores y encargados de su mantenimiento.

Existen diversos enfoques para combinar el código fuente y la documentación asociada:

  1. Usar ficheros separados para documentación y código
  2. Usar comentarios para incluir documentación en el código fuente
  3. Un fichero fuente completo puede estar englobado en un fichero de documentación
  4. El código fuente está descompuesto en fragmentos repartidos a lo largo de un documento

Documentación y código separados

Es el esquema usado implícitamente en el modelo de ciclo de vida en cascada. La documentación de diseño detallado debe redactarse y aprobarse antes de desarrollar el código fuente. No requiere ninguna herramienta o metodología especial, ya que cada fichero se prepara por separado.

Presenta el peligro evidente de inconsistencia. En particular es muy frecuente que el código fuente se modifique sin reflejar los cambios en la documentación asociada, que va quedando obsoleta a medida que avanza el desarrollo o el mantenimiento de la aplicación.

Además resulta incómodo manejar el conjunto código-documentación, ya que cada aspecto requiere herramientas diferentes, no es fácil presentar el código junto a su documentación, y mucho menos localizar rápidamente el punto concreto de documentación relacionado con un punto concreto del código, y viceversa.

Uso de comentarios en el código fuente

Posiblemente éste es el esquema más utilizado, combinado quizá con el anterior. Los lenguajes de programación permiten insertar texto libre entremezclado con el código fuente.

Las ventajas principales son el no necesitar una herramienta especial para preparar la documentación, y disponer de cada fragmento de documentación exactamente junto al elemento de código al que corresponde.

El inconveniente principal es la falta de estructuración del texto de los comentarios. Para paliar este inconveniente se han ideado diversos esquemas que permiten introducir como comentarios texto con formato similar al de un sistema convencional de preparación de documentación. JavaDoc (***ref***) es un claro ejemplo de uno de estos esquemas.

Código englobado en el texto de un documento

Este esquema consiste en tratar como código fuente una sección especial de un documento convencional. Es la forma general de preparar código fuente en el Sistema Oberon (***ref***), que es el entorno de programación asociado al lenguaje Oberon. En este entorno el código correspondiente a una unidad de compilación puede ser almacenado en un fichero específico, o bien aparecer como una sección más de un documento del entorno. El compilador se puede invocar directamente en cualquiera de los dos casos. Si hay errores de compilación, los mensajes de diagnóstico se insertan en el código fuente en el punto correspondiente, marcados de una manera adecuada.

Código entremezclado con el texto de un documento

Este es el esquema utilizado en la llamada Programación Letrada (Literate Programming: LP). Aquí se da prioridad a la documentación sobre el código. El código no aparece así reunido en un sólo punto, sino disperso a lo largo del documento. La organización del documento-código se elige de manera que resulte fácil de leer por parte de las personas interesadas, y no corresponde a la estructura propia del código fuente.

Para compilar el código hay que combinar primero los diferentes fragmentos mediante una herramienta especial denominada tangle. La generación del documento impreso se hace mediante otra herramienta denominada weave.

Documentación de código en EMU-Code

La propuesta de EMU-code es no representar el código fuente directamente como texto, sino con un marcado XML que codifique su estructura. Para compilar el código con un compilador convencional se puede generar el texto del código fuente con su representación convencional mediante una herramienta apropiada (XSLT o similar).

El esquema XML usado para marcar los elementos del código puede ampliarse sin restricción alguna para representar también los elementos de documentación. Así se podrá preparar conjuntamente la documentación y el código como un documento único, en el que no tiene que prevalecer la estructura de uno sobre la del otro. De esta manera se pueden desarrollar sin dificultad esquemas de combinación de cualquiera de los tipos indicados, o incluso otros intermedios o que mezclen elementos de varios de ellos.

Generadores de documentación

El código fuente con sus comentarios de documentación es en el fondo texto plano, por lo que las utilidades de impresión convencionales no permiten generar copias impresas fáciles de leer. Existen herramientas que permiten generar copias legibles y dan formato adecuado a cada fragmento de texto, construyen índices de elementos en el código, e incluso extraen y dan formato de documento a los comentarios de documentación, especialmente si se usa algún tipo de marcado documental dentro del texto de los comentarios. El formato final puede ser texto impreso o conjunto de páginas web, con enlaces entre los índices y los elementos de detalle, así como entre los elementos relacionados entre sí.

Ejemplos de estas herramientas son JavaDoc (Java), DoxiGen (C++), Ada-Browse (Ada), etc.

EMU-Code incluye utilidades para generación de documentación impresa con buena organización y presentación, a partir de la representación interna combinada del código y la documentación asociada. Estas utilidades generan automáticamente diagramas de estructura modular, índices de funciones y clases, etc.


Copyright © 2004 Manuel Collado: mcollado@fi.upm.es