Universidad de Costa Rica Escuela de Ciencias de la Computación e Informática

Resumen   

      Es difícil que un estudiante comprenda por qué es necesario usar abstracción al construir programas. Debido a que los profesores debemos formular reglas para la entrega de los proyectos programados de los estudiantes, podemos aprovechar esa autoridad para acostumbrarles a construirlos de manera que adquieran buenas prácticas de programación, las que luego pueden ser reforzadas con la justificación que las debe acompañar, como explico en [DiM-2007]: "... el uso de abstracción es de primordial importancia para construir programas y sistemas grandes; esta es la mejor forma que conocemos para delegar en otros programadores la implementación de los módulos de un programa. Por eso, la especificación de artefactos de programación es la herramienta principal usada para diseñar programas construidos con componentes reutilizables". (La versión HTML de este documento incluye muchos enlaces a las definiciones de la mayor parte de los conceptos aquí discutidos).

      Para la mayor parte de los programadores la codificación de algoritmos es la parte más interesante de la construcción de programas; los programadores trabajamos creando mundos virtuales, en donde todas las variables coexisten bajo nuestro perfecto control: esta es la parte más creativa del trabajo del programador. Para construir programas los programadores usamos muchos trucos, desde el uso de estructuras de datos y algoritmos avanzados, hasta la aplicación de convenciones como las descritas en [DiM-1988], que facilitan la labor de programación y mantenimiento del programa.

      Es posible describir muchas reglas que resultan en una mejor implementación, como por ejemplo las convenciones descritas en:

•	[DiM-1988]	==>	http://www.di-mare.com/adolfo/p/convpas.htm
•	[KNDK-1997]	==>	http://java.sun.com/docs/codeconv/CodeConventions.pdf
•	[Hunt-1998]	==>	http://weblogs.asp.net/lhunt/pages/CSharp-Coding-Standards-document.aspx

      Yo sigo un camino más sencillo pues les pido a mis estudiantes que al escribir su implementación, deben asegurarse de cumplir siempre con estas 3 políticas de programación, que considero las más importantes:

1. Es muy importante que el programa esté correctamente indentado y que las instrucciones estén debidamente espaciadas.
2. Es muy importante que en todo el programa haya buena documentación interna.
3. Uso de Doxygen para la especificación de todos los métodos, funciones y campos de la clase.

      Mis asistentes saben cuál es la forma de calificar proyectos programados. Específicamente, se concentran en encontrar fallas que quiebren alguna de estas 5 reglas:

1. La falta de cualquier especificación debe ser castigada fuertemente.
2. Correcta indentación del código fuente.
3. Correcto espaciado del código fuente.
4. Código fuente escrito de manera que sea legible y claro.
5. Uso de identificadores significativos.

PROJECT_NAME          = "Prueba de la clase rational:"
OUTPUT_LANGUAGE       = Spanish
OUTPUT_DIRECTORY      = .
GENERATE_LATEX        = NO
GENERATE_MAN          = NO
GENERATE_RTF          = NO
CASE_SENSE_NAMES      = YES
INPUT_ENCODING        = ISO-8859-1
INPUT                 = rational.h rational.cpp rat-calc.cpp \
                        rat-tst.cpp ADH_port.h
RECURSIVE             = NO
QUIET                 = YES
JAVADOC_AUTOBRIEF     = YES
EXTRACT_ALL           = YES
EXTRACT_PRIVATE       = YES
EXTRACT_STATIC        = YES
EXTRACT_LOCAL_CLASSES = YES
INLINE_INHERITED_MEMB = YES
SOURCE_BROWSER        = YES
INLINE_SOURCES        = NO
STRIP_CODE_COMMENTS   = NO
REFERENCED_BY_RELATION= NO
REFERENCES_RELATION   = NO
FULL_PATH_NAMES       = NO

SORT_MEMBER_DOCS      = NO
SORT_BRIEF_DOCS       = NO
CLASS_DIAGRAMS        = YES

ENABLE_PREPROCESSING  = YES
MACRO_EXPANSION       = YES
EXPAND_ONLY_PREDEF    = YES
PREDEFINED            = "DOXYGEN_COMMENT" \
                        "Spanish_dox" \
                        "__cplusplus" \
                        "_MSC_VER=1300" \
                        "OPEN_namespace(N)=namespace N {" \
                        "CLOSE_namespace(N)=}" \
                        "USIGN_namespace(N)=using namespace N"
EXAMPLE_PATH          = .

#--- TODOS ESTOS SON MENOS COMUNES ---
# DISTRIBUTE_GROUP_DOC = YES
# ENABLE_PREPROCESSING = YES
# FILE_PATTERNS        = diagrams_*.h
# GENERATE_TAGFILE     = example.tag
# HAVE_DOT             = YES
# PERL_PATH            = perl
# TAGFILES             = example.tag=../../example/html

# Manual ==> http://www.doxygen.org/manual.html

1. Configuración Doxygen   

      Doxygen es un sistema de documentación para C++, C, Java, Objective-C, Python, IDL (Corba y los sabores Microsoft) y, hasta cierto punto, para PHP, C# y D. La ventaja principal de usar Doxygen en los cursos universitarios es que le permite al estudiante obtener entrenamiento en el uso herramientas que ayudan a generar documentación con la ventaja adicional de que Doxygen es aplicable a un rango muy amplio de lenguajes, lo que no ocurre con herramientas de aplicación específica como Javadoc [KNDK-1997]. Cuando el estudiante termina sus estudios universitarios y pase a su carrera profesional, su entrenamiento Doxygen le permitirá usar con comodidad cualquier otra herramienta de documentación, inclusive Javadoc, cuyo formato es compatible con Doxygen.

      En la Figura 1 se muestra el archivo "rat-tst.dxg" que se puede usar de plantilla para obtener el archivo de configuración para que Doxygen gener la documentación de uno o más módulos. Para esto, basta modificar únicamente el renglón "INPUT" que contiene la lista de archivos de donde Doxygen extraerá la documentación. En este ejemplo, Doxygen generó documentación usando como entrada los siguientes archivos: "rational.h", "rational.cpp", "rat-calc.cpp", "rat-tst.cpp" y "ADH_port.h".

/** Calcula el Máximo Común Divisor de los números \c "x" y \c "y".
    - <code> mcd(x,y) >= 1 </code> siempre.
    - MCD <==> GCD: <em> Greatest Common Divisor </em>.

    \pre
    <code> (y != 0) </code>

    \remark
    Se usa el algoritmo de Euclides para hacer el cálculo.

    \par Ejemplo:
    \code
    2*3*5 == mcd( 2*2*2*2 * 3*3 * 5*5, 2*3*5 )
       30 == mcd( -3600, -30 )
    \endcode
*/
long mcd(long x, long y) {
    long g = (x < 0 ? -x : x); // trabaja con valores positivos
    long r = (y < 0 ? -y : y); // "r" es el resto
    long temp;

    do {
        temp = r;
        r    = g % r;
        g    = temp;
    } while (0 != r);

    return g;
}  // mcd()

      El estilo Doxygen de documentación es bastante simple e intuitivo, como se muestra en la Figura 2. En resumen, lo más relevante que hay que saber para usar esta herramienta es lo siguiente:

• La documentación Doxygen comienza con el marcador de principio de comentario "/**" y termina en "*/". Esto permite mezclar la documentación con el código fuente lo que ayuda mucho a que la documentación quede actualizada cuando se le da mantenimiento a un módulo.
• El primer renglón de la documentación permite definir para qué sirve el artefacto de programación. Este renglón finaliza con un punto "." que no hay que olvidar y es el que sale el la documentación general del módulo. Por ejemplo, se puede consultar en Internet la página descriptiva para las clases "Matrix" descrita en [DiM-2004] y "rational", que es la clase usada como ejemplo en este documento:
       http://www.di-mare.com/adolfo/p/Matrix/classMx_1_1Matrix.html
     http://www.di-mare.com/adolfo/p/rational/classADH_1_1rational.html
• Los comandos especiales Doxygen "\pre", "\remarks" y "\par" permiten agregar secciones de precondición, comentarios y ejemplos a la documentación.
• También es posible incluir ejemplos de uso con los marcadores HTML "<code>" y "</code>" o con sus equivalentes, los comandos especiales "\code" y "\endcode", que sirven para incluir texto usando una fuente no proporcional, similar a la fuente "Courier" generalmente usada para el código de programas.
• Doxygen también permite usar listas, las que se obtienen anteponiendo un guión al principio de cada ítem de la lista.

    2*3*5 == mcd( 2*2*2*2 * 3*3 * 5*5, 2*3*5 )
       30 == mcd( -3600, -30 )

      En la Figura 3 se muestra la documentación que Doxygen genera para "mcd()". Debido a que el prototipo o encabezado de cualquier función o método forma parte de su especificación, a los novatos que me lo preguntan yo siempre les digo: "la especificación comienza con el primer caracter de la documentación Doxygen de cada método o función, y termina donde está el corchete abierto "{" que marca la implementación del algoritmo en el código fuente del programa".

      Algunos hábitos son más fáciles de inculcar que otros. Por ejemplo, es mejor usar la codificación de "pruebe primero y luego programe" (test first then code") [Hunt-1998]. Como para construir un programa de prueba hay que saber programar, esta estrategia no se le puede enseñar a quien nunca ha programado. Debido a que Doxygen genera una página sumaria para cada módulo que procesa, es posible revisar esa página para determinar si están completas todas las especificaciones de las rutinas implementadas en el módulo (esta página es la mencionada anteriormente para las clases "Matrix" y "rational"). Si falta la documentación de algún módulo, en esa página aparecerá el vacío respectivo y será muy sencillo pedirle al programador que corrija la omisión. Luego es posible también afinar y mejorar las especificaciones, que están incluidas junto con el algoritmo de cada rutina. La Figura 4 es un ejemplo en el que se nota claramente que la documentación para el método "Remingue()" no existe, pues aparece en blanco su descripción corta.

2. Guía para documentar programas   

      Muchos programadores no saben escribir la documentación de sus programas, pues nunca lo han hecho, y porque nunca les han dado una guía para hacerlo. El problema que tiene usar una guía es que las personas tienen la tendencia de seguirla a ciegas, como si fuera la única forma de hacer las cosas. La guía que aquí presento no debe ser usada de esa manera, pues en algunos casos no se aplican alguna de su partes, mientras que en otros casos esta guía se queda más bien corta.

      La lista de ítems que incluye la guía para documentar programas que se muestra en la Figura 5 a veces confunde a mis estudiantes, pues no saben con qué "rellenar" la sección de "Abstracción" o la de "Planteo". Mi respuesta a sus inquietudes siempre incluye el siguiente principio: "La documentación se hace para otras personas, no es para uno mismo. Por eso, la documentación debe servir para que otra persona pueda conocer rápidamente lo que necesita para usar el programa y también para modificarlo".

3. Tabla de calificación   

      A veces los estudiantes necesitan saber qué pierden y cuánto pierden al hacer sus trabajos y proyectos. Pare eso resulta muy útil definir una tabla de calificación, que muestre el puntaje que debe ser asignado a cada ítem.

      El gran total (8+8+8+6) + (15+15) + (10+15+15) es 100%, que es la suma del primer valor de calificación para cada uno de los ítems en la tabla de calificación de la Figura 6, adaptado de [Casa-2004]. La escala de calificación usada va de mayor a menor: excelente, muy bueno, bueno, regular y malo. El factor de completitud se usa para modular el resultado global del trabajo porque si el programa no produce los resultados correctos, la evaluación no puede ser 100%.

4. Formato de entrega   

      La entrega de cualquier proyecto programado debe contener 2 partes: un documento impreso y los archivos con el programa. El documento impreso generalmente no contiene toda la documentación Doxygen, pues es posible generarla basta con base en el archivo de configuración similar al de la Figura 1. Los archivos del programa generalmente son entregados por correo electrónico a una dirección predeterminada en el enunciado del proyecto, en un único archivo empacado ".zip" cuyo nombre sea la identificación del estudiante y que incluya en ese archivo lo siguiente:

1. Un documento en formato HTML que describa el trabajo realizado. Debe mencionar cuál compilador usó.
2. La especificación del programa.
3. Archivo de configuración Doxygen (los asistentes usan este archivo de configuración para generar la documentación del programa, por lo que sobra que el alumno incluya esa documentación en su archivo .zip).
4. El código fuente de los programas (archivos de implementación *.c, *.cpp, *.h, etc.).
5. Los archivos y datos de prueba para el programa.
6. Un archivo de enlace Internet, con extensión ".url" que permita abrir la página Internet en que está la documentación completa de su programa.

      Por ejemplo, para entregar su proyecto HerenciaOrdenada.cpp el estudiante 952809 crea su archivo 952809.zip que contenga los siguientes archivos:

HerenciaOrdenada.cpp

Ejemplo de uso de funciones virtuales usando algoritmos de ordenamiento.

 

ADH_port.h

Encabezado para que los programas puedan ser compilados con varios compiladores

ADH_test.h

Módulo para prueba unitaria de programas

 

952809.doc

Documentación, escrita con Word (incluye la portada)

952809.htm

Página Internet con toda la documentación

952809.dxg

Archivo de configuración Doxygen.

952809.url

Enlace para abrir la página Internet

 

HerenciaOrdenada.dsp

Archivo para compilar el programa con MSC++ v6.x

HerenciaOrdenada.vcproj

Archivo para compilar el programa con MSC++ .NET

Conclusión   

      Para construir programas es necesario seguir un conjunto de buenas prácticas que facilitan la labor, reducen el costo y hacen más fácil el mantenimiento de los módulos. El buen programador usa:

• Abstracción: para diseñar los programas por capas y por módulos.
• Especificación: para definir el rol de cada módulo en el sistema y para facilitar su reutilización.
• Encapsulamiento: para que quede junto lo que debe estar junto.
• Ocultamiento de datos: para evitar que el programador cliente tenga que lidiar con los detalles de implementación.

      El uso de Doxygen permite inculcar con facilidad estas buenas prácticas en el programador novato. Tiene la ventaja adicional de ser un herramienta que sirve para muchos lenguajes, por lo que sirve de punto de partida para cualquier otra plataforma.

Agradecimientos   

      Alejandro Di Mare aportó varias observaciones y sugerencias importantes para mejorar este trabajo.

Código fuente   

Bibliografía   

Indice   

[-]	Resumen
[1]	Configuración Doxygen
[2]	Guía para documentar programas
[3]	Tabla de calificación
[4]	Formato de entrega
[-]	Conclusión
[-]	Agradecimientos
[-]	Código fuente
	Bibliografía
	Indice
	Acerca del autor
	Acerca de este documento
	Principio Indice Final

Acerca del autor   

Adolfo Di Mare <adolfo@di-mare.com>

Acerca de este documento   

Referencia:	Di Mare, Adolfo: Uso de Doxygen para especificar módulos y programas, I Congreso Internacional de Computación y Matemática, (CICMA-2008), celebrado del 21 al 23 de agosto en la Universidad Nacional (UNA), Costa Rica, I.S.B.N.: 978-9968-9961-1-5, 2008.
Internet:	http://www.di-mare.com/adolfo/p/Doxygen.htm
Autor:	Adolfo Di Mare <adolfo@di-mare.com>
Contacto:	Apdo 4249-1000, San José Costa Rica Tel: (506) 207-4020       Fax: (506) 438-0139
Revisión:	ECCI-UCR, Enero 2007
Visitantes: