Lenguaje de Programación C++

Unidad IV. Recomendaciones integración de código

Objetivos:

• Conocer las mejores prácticas de codificación para facilitar la lectura y

comprensión del código.
• Aprender a documentar el código en C++ de una manera adecuada
para futuro mantenimiento.
• Generar una versión portable de la documentación del programa para
lectura en general.
• Buscar errores lógicos en tiempo de ejecución de un programa de C++.
• Evitar que un programa en C++ termine abruptamente.

1
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Generación automática de documentación

Una opción muy popular para la generación automática de documentación de código es la

herramienta gratuita Doxygen. Su flexibilidad radica en el soporte para varios lenguajes de
programación, incluyendo C++, así como en los formatos de salida posibles, que incluyen
HTML y PDF. Adicionalmente, Doxygen es multi-plataforma: tiene soporte para sistemas
operativos basados en Unix, Windows, y MacOS.

A grandes rasgos, Doxygen genera la documentación automáticamente a partir del

código fuente comentado, el cual debe seguir cierta nomenclatura. Numerosas
opciones para la generación pueden ser especificadas a través de un archivo de
configuración propio de Doxygen.

Características adicionales de esta herramienta incluyen la generación de diagramas de

herencia y estructura del código, entre otras.

Documentando el código según Doxygen

En esta sección se describe cómo poner los comentarios en el código de tal manera que
Doxygen los incorpore en la documentación que genera.

Se le llama un bloque de comentarios especial a un bloque de comentarios del estilo

de C o C++ con algunas marcas adicionales que le indican a Doxygen que es un
fragmento de texto estructurado que se necesita agregar a la documentación
generada.

Doxygen documenta archivos, funciones, clases, miembros y atributos, siendo estos últimos
temas por ver en unidades posteriores.

El bloque de comentarios (normal) y el bloque de comentarios especial pueden convivir en el

mismo código, sin embargo únicamente el especial es el que Doxygen tomará para generar la
documentación. En este caso, el bloque de comentarios (normal) se utiliza para notas
explicatorias que no refieren a la descripción de alguna función, clase, miembro o atributo
como, por ejemplo, para indicar separación de porciones de código, declaración de variables
locales de una función, títulos de algunas porciones de código, etc.

Un bloque de comentarios especial al estilo de C++ se identifica al agregar un asterisco *

adicional o un signo de exclamación ! en el primer delimitador del bloque de comentarios. Por
ejemplo:

/**
<...texto...>
*/

2
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

/*!
<...texto...>
*/

También existe la alternativa de colocar asteriscos al comienzo de cada línea dentro del bloque
de comentarios, como se muestra en los siguientes ejemplos.

/**
* <...texto...>
*/

/*!
* <...texto...>
*/

El bloque de comentarios especial puede contener una descripción breve y una descripción
detallada, esta última siendo opcional. Si ambas se redactan, primeramente se coloca la
descripción breve y se separa con una línea en blanco de la descripción detallada, por ejemplo

/**
* <Una línea corta de descripción breve>
*
* <Descripción detallada en todas las líneas que sean necesarias>
*/

En el bloque de comentarios especial se pueden especificar ciertos campos ya establecidos por

Doxygen dependiendo de la entidad que se está comentando (función, clase, variable, archivo,
etc.). Al nombre de cada campo le precede un arroba @, lo cual lo identifica como un campo
de Doxygen. También es utilizada la diagonal / en lugar del arroba @ en el nombre de los
campos.

Para el encabezado de un archivo, los campos comúnmente utilizados son @file, @author,
@date, @version y @section. Enseguida se muestra un ejemplo:

3
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

/**
* @file <nombre del archivo>  
* @author <nombre del autor y se puede agregar su correo electrónico>  
* @version <número de versión>  
* @date <fecha de creación o última revisión>  
*
* @section LICENCIA  
*
* <descripción de la licencia que posee, pueden utilizarse múltiples
* líneas escritas y líneas en blanco>
*
* @section DESCRIPCIÓN  
*
* <descripción breve y/o detallada, pueden utilizarse múltiples
* líneas escritas y líneas en blanco >
*/

Con el campo de @section, se pueden redactar los apartados que se deseen. En el encabezado se
debe especificar que la descripción es una sección. Para fines del curso, los campos que se pide
conservar para los ejercicios de esta Unidad, y las siguientes, son como mínimo @file, @author,
@date y @section DESCRIPCIÓN.

Luego, para funciones se utilizan los campos @param y @return en su bloque de comentarios.
El siguiente código presenta un ejemplo:

/**
* <Una línea corta de descripción breve>
*
* <Descripción detallada en todas las líneas que sean necesarias>
*
* @param parametro1 Descripción del parametro1 de entrada de la función
* @param parámetro2 Descripción del parametro2 de entrada de la función
* ...
* @return Descripción del valor de salida de la función
*/

Como opcional, existe el campo @brief en el cual se especifica la descripción.

Dentro del bloque de comentarios especial es posible poner ecuaciones matemáticas

empleando comandos de Látex.

Es posible especificar que el bloque de comentarios especial se encuentra después del código a
comentar, agregando el signo < en el primer delimitador del bloque. Por ejemplo:

<tipo de salida> <funcion>(<parametros>); /**< Descripción */

Este tipo de bloque se comentarios se utiliza generalmente para descripciones breves en las
declaraciones de funciones y miembros de una clase (tema por ver en la Unidad 6).

4
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Existen otros estilos para estos bloques de comentarios especiales, pero no entraremos
en detalle en este curso. Si se desea conocer estos estilos, la página oficial de Doxygen
presenta descripciones y ejemplos, véase

http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

Ejecutando Doxygen

Luego de instalar Doxygen y de agregar los comentarios en el código según el estilo de

Doxygen, en esta sección se mostrará como ejecutar Doxygen para que realice la
documentación del programa.

La liga donde se encuentran las opciones de descarga de Doxygen es la siguiente:

http://www.stack.nl/~dimitri/doxygen/download.html

Existen varias formas de ejecutar Doxygen: por línea de comandos (terminal o símbolo del
sistema) o por la interfaz gráfica Doxywizard.

Si se desea conocer con mayor detalle las formas de ejecución de Doxygen y las
diferentes opciones de configuración, véase la información de la liga:
http://www.stack.nl/~dimitri/doxygen/manual/starting.html

Code::Blocks presenta el plugin DoxyBlocks que integra a Doxygen. Este plugin se encuentra
en la barra de menús y se muestra en la siguiente figura las opciones que despliega.

Figura 1. Opciones del menú DoxyBlocks en Code::Blocks.

La primera opción “Doxywizard…” abre la interfaz gráfica Doxywizard. Otra forma más
directa es la segunda opción “Extract documentation” la cual se enlaza con Doxywizard
automáticamente y genera la documentación con la configuración por defecto de Doxygen.

5
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

La opción “Block comment” inserta la plantilla del bloque de comentarios especial donde se
encuentre el cursor. La opción “Line comment” inserta, donde se encuentre el cursor, los
delimitadores del tipo de bloque de comentarios especial que se encuentra después del código a
comentar.

Para visualizar la documentación en el HTML donde se generó la documentación del proyecto

de Code::Blocks, se pulsa la opción “Run HTML” que abre en el navegador por defecto la
página web de la documentación. La opción “Run CHM” abre la documentación de ayuda,
requiere especificaciones en la configuración de Doxygen para generarse y no se verá a detalle
en este curso.

La opción “Open preferences…” muestra las diversas especificaciones de la configuración para

Doxygen en la generación de la documentación para el proyecto. Luego, “Load settings
template” indica utilizar la configuración guardada para la documentación de este proyecto. Y
“Save settings template” indica guardar la configuración actual que se ha manejado para
Doxygen.

En el proyecto anexo U4_3_ejemploDoxygen se encuentra el código de ejemplo donde se

encuentran comentados los encabezados de archivos y las funciones según la nomenclatura de
Doxygen para crear la documentación automática. También se encuentran comentadas las
declaraciones de variables locales, los títulos de las secciones del código, entre otros, con el
estilo de C++ que será ignorado por Doxygen.

Para generar la documentación de Doxygen, se necesita indicar en la configuración que

considere los bloques de comentarios especiales de las funciones, ya que no lo presenta por
defecto. Para esto, se selecciona la opción “Open preferences…” y en el cuadro de diálogo que
aparece se dirige hacia la pestaña de “Doxyfile Defaults”, véase figura 2. Se verifica que este
palomeada la casilla de verificación de EXTRACT ALL que se encuentra en la sección “Build”
y se le da click en “OK”.

6
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Figura 2. Cuadro de diálogo de “Open preferences” de DoxyBlocks en el apartado de “Doxyfile Defaults”.

En este mismo cuadro de diálogo se encuentra el parámetro OUTPUT_LANGUAGE donde se

especifica el idioma que presentará la documentación.

Luego, para ejecutar Doxygen se selecciona la opción “Extract documentation”. En el apartado

“Logs & others” de la parte inferior de la ventana de Code::Blocks aparece la pestaña de la
consola de “DoxyBlocks” y se muestra el avance y resultados de la ejecución de DoxyBlocks. Si
la ejecución fue exitosa, es posible visualizar la documentación generada a partir de
Code::Blocks mediante la selección de la opción “Run HTML”.

Como se había mencionado anteriormente, también es posible ejecutar Doxygen entrando

directamente a la interfaz Doxywizard donde se pueden especificar más parámetros de
configuración que permiten adecuar la documentación según nuestras necesidades, por
ejemplo, el encode del archivo HTML que se genera.

Para abrir Doxywizard tenemos dos opciones: abrir desde Code::Blocks en la pestaña de
DoxyBlocks o abrir en las aplicaciones instaladas en la computadora. Al abrir Doxywizard se
presenta el siguiente cuadro de diálogo:

7
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Figura 3. Cuadro de diálogo inicial de “Doxywizard”.

En la sección “Step 1” debe indicarse la ruta a la carpeta existente desde la cual se ejecutará
Doxygen.

En la parte derecha de “Step 2” puede detallarse el nombre, la sinopsis, el identificador y el

logo del proyecto. En el bloque “Specify the directory to scan for source code” se indica el
directorio donde se encuentra el código a documentar y se palomea la opción de “Scan
recursively” para que también documente los códigos que se encuentren en todas las carpetas
contenidas en ese directorio (subcarpetas, subsubcarpetas, etc). Al final, en el bloque “Specify
the directory where Doxygen should put the generated documentation” se refiere a especificar
el directorio en el cuál se guardará la documentación generada. Si este último directorio no es
indicado, la documentación se guardará en la carpeta de “Step 1”.

Para indicar que se active el parámetro EXTRACT_ALL (que indica se extraiga toda la
documentación del código fuente al archivo HTML), se da click en la pestaña de “Expert” de la
parte izquierda de “Step 2”. Luego, se selecciona el tópico “Build”. Se verifica que la casilla de
verificación de EXTRACT_ALL se encuentre palomeada. El cuadro de diálogo que se observa
es el siguiente:

8
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Figura 4. Localización del parámetro EXTRACT_ALL en “Doxywizard”.

La especificación del idioma en la documentación de Doxygen, se realiza dirigiéndose al tópico

“Project” y seleccionar el idioma en el parámetro OUTPUT_LANGUAGE. Si se desea el
idioma español, la figura de enseguida muestra este parámetro ajustado.

Figura 5. Localización del parámetro OUTPUT_LANGUAGE en “Doxywizard”.

9
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

Para que los acentos se observen en la documentación, es necesario cambiar otro parámetro.
En el tópico “Input” se encuentra el parámetro INPUT_ENCODING y debe tener el valor de
ISO-8859-1. La figura siguiente lo muestra.

Figura 6. Localización del parámetro INPUT_ENCODING en “Doxywizard”.

Ya que están todos estos parámetros indicados, se puede ejecutar Doxygen dirigiéndose a la
pestaña “Run” y dar click en el botón “Run doxygen”, que se observa en la siguiente figura.

Figura 7. Cuadro de dialogo de ejecución de "Doxywizard".

10
 Lenguaje de Programación C++
Unidad IV. Recomendaciones integración de código

En el rectángulo en blanco se observa el progreso de la ejecución de Doxygen. En el ejemplo de

la figura vemos que la generación de la documentación finalizó correctamente. Si se da click en
el botón “Show HTML output” se abrirá la documentación en el navegador predeterminado.

Otra forma de abrir la documentación es dirigirse a la carpeta donde se guardó la

documentación (en este caso, en la carpeta doxygen que se encuentra en el directorio del
proyecto) y en la subcarpeta html se encuentra el archivo index.html, al abrir este archivo en
algún navegador se mostrará la documentación generada.

A partir de esta Unidad, se pedirá incluir también el tipo de documentación de código por
Doxygen en las actividades del curso. El código de U4_3_ejemploDoxygen muestra un ejemplo
de la documentación de código que puede servir de guía.

Actividad optativa: Visualice el video “Manejo de Doxygen” donde se muestra un

ejemplo de cómo generar automáticamente la documentación del código utilizando
Doxygen.

Actividad a evaluar: Realice la actividad 1 de esta semana en la plataforma del curso

en línea.

11