Algorítmica y Programación. Unidad 2: Estándares de Calidad en el Diseño de Algoritmos y Construcción de Programas. Tema 2.3: Documentación.

1. 2.3.- DOCUMENTACIÓN
Unidad 2:
Estándares de Calidad en el Diseño de Algoritmos y
Construcción de Programas
Conocer las características e importancia de una
documentación de sistemas informáticos adecuada y
eficiente.
Profa. Yenny Salazar

2. CONTENIDO
 Documentación de un Programa
• Documentación Interna
– Comentarios
o Prólogo
o Directorios
o Explicatorios
• Documentación Externa
– Características
– Documentación de Usuario
o Manual de Usuario
∙ Crear la Documentación de Usuarios Apropiada
∙ Organizar los Componentes del Manual de Usuario
∙ Diseñar un Manual de Usuario Legible
– Documentación del Sistema
o Manual de Mantenimiento
∙ Documentación para Programadores
 Observaciones Generales
 Actividades
 Referencias

3. DOCUMENTACIÓN DE UN PROGRAMA
 Es una pieza clave en la ingeniería de software, que permite a
sus usuarios aprender a utilizar y mantener el producto.
 Consta de las descripciones de los pasos que se dan durante el
proceso de desarrollo del sistema.
 Su importancia debe ser destacada por su decisiva influencia
en el producto final; pues los software deficientemente
documentados son difíciles de leer, más difíciles de depurar y
casi imposibles de mantener y modificar.
• Puede ser interna y externa.
– La interna es la contenida entre las líneas de código (comentarios)
– La externa incluye análisis, diagramas y/o pseudocódigos,
manuales de usuario con instrucciones para ejecutar el programa e
interpretar los resultados, así como los manuales de sistemas.
– Se produce normalmente para dos fines:
o La documentación de usuario: explica las características del
software y describe cómo utilizarlo.
o La documentación del sistema: describe
la composición interna del software, de
modo que el sistema pueda ser mantenido
a lo largo de su ciclo de vida.

4. DOCUMENTACIÓN INTERNA
COMENTARIOS
 Prólogo: se trata de los comentarios que acompañan a cada
subprogramas (rutinas):
• Finalidad de la rutina.
• Significado de las variables más importantes.
• Indicaciones generales de cómo trabaja la rutina.
• Comentarios relevantes para utilizarla (parámetros, efectos
laterales, etc.).
/***********************************************************************************
* Nombre de la rutina *
* Finalidad: Explica lo que la rutina hace (no cómo lo hace). *
*Entradas: Lista las variables de entrada y su significado. *
* Salida: Lista los parámetros de salida y su significado. *
* Retorna: Indica el significado del valor devuelto por la rutina *
* (en caso de que devuelva alguno) *
* Globales: Indica las variables globales que necesita la rutina. *
* Efectos-laterales: Indica cualquier cambio que produzca la ejecución *
* de la rutina.
***********************************************************************************/

5. DOCUMENTACIÓN INTERNA
COMENTARIOS
 Directorio: son comentarios que se sitúan al principio de los
ficheros que componen un programa e indican fundamental-
mente los subprogramas contenidos en dicho fichero. Por lo
general esto comentarios incluyen la siguiente información:
• Autor.
• Fecha.
• Proyecto del que forma parte el fichero: práctica de una
asignatura, proyecto de programación, etc.
• Rutinas contenidas en el fichero y finalidad de cada una de ellas.
 Explicatorios: son los comentarios que se colocan en cualquier
lugar del código para explicar partes del mismo. Pueden ser
comentarios de una sola línea o bien de un cierto número de
ellas (comentarios de tipo bloque).
Es una buena idea que los comentarios de tipo bloque vayan
delimitados por algún tipo de caracteres que los hagan
claramente visibles.

6. DOCUMENTACIÓN INTERNA
COMENTARIOS
Ejemplo de comentarios explicatorios de bloques:
/****************************************************************************
* Los comentarios de tipo bloque contienen texto en lenguaje *
*natural (evitar las faltas de ortografía) y constan generalmente de *
*varias líneas. *
* Generalmente ayuda a su legibilidad el dejar líneas en blanco *
*entre cada uno de los párrafos del comentario. *
* Tienden a ser comentarios de una o dos líneas. *
****************************************************************************/
Los comentarios de bloque tienen varias ventajas:
• Los bloques quedan marcados claramente y así son fáciles de
encontrar.
• Las frases del comentario se pueden modificar fácilmente
conforme se hacen correcciones en el código fuente.
• Los comentarios no aparecen dispersos de forma anárquica sino
que se concentran en puntos concretos.
• No se invierte demasiado tiempo en comentarios que no
conllevan información.

7. DOCUMENTACIÓN INTERNA
COMENTARIOS
Los comentarios explicatorios de una línea se utilizan para
aportar información adicional en ciertos puntos del código. Por
ejemplo:
x[i]==a[j]; // x[i] es ahora el mayor elemento
Estos deben ir al final de la misma línea que la sentencia y se
reservan para situaciones como:
• Identificar los diferentes casos en una sentencia.
• Identificar las sentencias de finalización de un bloque de código.
• Mostrar invariantes de bucle.
• Explicar expresiones complejas.
• Explicar el motivo de algunas acciones concretas en el código.
Muchos comentarios cortos oscurecen el código, es preferible
incluirlos en un comentario prólogo.
Una buena regla es que un código debería contener un
promedio de una línea de comentario por cada 10 líneas de
código ejecutable.

8. DOCUMENTACIÓN EXTERNA
 No forma parte del programa fuente, es en un manual que
acompaña al programa.
 La documentación externa debe incluir:
• Listado actual del programa fuente, mapas de memoria,
referencias cruzadas, etc.
• Especificación del programa: documento que define el propósito
y modo de funcionamiento del programa.
• Diagrama de estructura que representa la organización jerárquica
de los módulos que comprende el programa.
• Explicaciones de fórmulas complejas.
• Especificación de los datos a procesar: archivos externos
incluyendo el formato de las estructuras de los registros, campos
etc.
• Formatos de pantallas utilizados para
interactuar con los usuarios.
• Cualquier indicación especial que
pueda servir a los programadores que
deben mantener el programa.

9. DOCUMENTACIÓN EXTERNA
CARACTERÍSTICAS
 Es útil para describir:
• Cómo usar el sistema (sin esto aún el sistema más simple
resultaría Inútil).
• Cómo instalar y operar con el sistema.
• Los requisitos y el diseño de todo el sistema.
• La función del sistema y los procedimientos de prueba, para hacer
el mantenimiento al sistema.
 No tiene por qué producirse en el mismo orden que el sistema
(pueden adelantarse trozos, aunque no es conveniente atrasarlos)
 Necesita índices efectivos, para poder encontrar la información
 Puede venir dada en distintos formatos:
• Escrito
• Informático (base de datos, texto, ...)

10. DOCUMENTACIÓN DE USUARIO
 Está diseñada para ser leída por el usuario del software, por
consiguiente no debe ser técnica.
 Combinada con una interfaz de usuario bien diseñada hace un
paquete de software accesible.
 Es un instrumento comercial importante. Una buena
documentación de usuario hará al programa más asequible.
 El manual de usuario debe cubrir al menos los siguientes
puntos:
• Órdenes necesarias para cargar el programa en memoria desde el
almacenamiento secundario (disco) y arrancar su funcionamiento.
• Nombres de los archivos externos a los que accede el programa.
• Formato de todos los mensajes de error o
informes.
• Opciones en el funcionamiento del programa.
• Descripción detallada de la función realizada
por el programa.
• Descripción detallada, preferiblemente con
ejemplos, de cualquier salida producida por el
programa.

11. MANUAL DE USUARIO
 Sirve para educar al usuario acerca de las funciones del
producto software mientras le enseña a utilizarlo de manera
efectiva.
 Están dispuestos de tal forma que puedan leerse y consultarse
fácilmente.
 Debe crearse con un contenido efectivo y diseñado con la
disposición adecuada
 Crear la Documentación de Usuarios Apropiada:
1. Define quién es el usuario de la guía.
2. La experiencia que tienen los usuarios con
el producto o con otros productos similares.
3. Explicar a detalle el problema que el
usuario intenta resolver y luego presenta
una solución para dicho problema.
 Organizar los componentes del
manual de usuario:

12. Crear la Documentación de Usuarios Apropiada
1. Define quién es el usuario de la guía: se debe desarrollar un perfil
del usuario, tomando en cuenta lo siguiente: a) Lugar donde se
utilizará, esto puede determinar el contenido y el estilo del manual.
b) La manera en que se utilizará la guía de usuario. Si los usuarios
consultarán el manual pocas veces o solo para buscar información,
esta debe tener un formato como el de un documento de consulta.
Si al principio los usuarios consultarán el manual con frecuencia, la
sección de consulta debe estar acompañada de una sección titulada
“Cómo empezar” y de instrucciones de las tareas más simples para
las que se utilizará el producto.
2. La experiencia que tienen los usuarios con el producto o con otros
productos similares: Si tu producto es nuevo o significativamente
diferente de otros productos similares, deberás incluir una
explicación de cómo es distinto comparado con otros productos y
también instrucciones de cómo comenzar a utilizarlo. Si el producto
está relacionado con algo que frecuentemente resulta problemático
para los usuarios, como sucede con muchos programas de
computación, deberás proporcionar una información adecuada y
detallada de una forma comprensible

13. Crear la Documentación de Usuarios Apropiada
3. Explicar a detalle el problema que el usuario intenta resolver y
luego presenta una solución para dicho problema: Ofrecer una
característica del producto como una solución a un problema,
funciona bien cuando se promociona el producto, pero una vez que
el usuario lo tenga, debe saber cómo utilizar dicha característica.
Identificar y mencionar los problemas específicos que el usuario
enfrentará, añadiendo las instrucciones para resolverlos; para
problema complejos, separarlos en partes más pequeñas; dividir la
información de esta manera se denomina fragmentar.

14. Organizar los Componentes del Manual de Usuario
1. Portada y las carátulas adecuadas: Incluir una portada para cualquier
guía de usuario, así como una carátula para cualquier manual. Si el
manual tiene la protección de los derechos de autor, se debe incluir un
aviso en la portada y en la carátula. Si existen términos y condiciones
para usar el manual y el producto asociado a este, colócalos en la
portada interior.
2. Referencias a documentaciones relacionadas en el prefacio: Si la
documentación de usuario es más que un solo manual, coloca las
referencias a los demás documentos, con sus números de versiones
correspondientes. El prefacio también es el lugar en donde se deberá
colocar (si la hubiera) una sección denominada «Cómo utilizar esta
guía».
3. Índice de contenidos: incluir si el manual excede las 10 páginas.
4. Cuerpo del manual: Mantener una estructura consistente. Comenzar
con un resumen y enumerar los pasos en cada sección. Incluir
instrucciones, procedimientos, materiales de consulta, lista de
opciones, consejos para la resolución de problemas y preguntas más
frecuentes. El glosario puede añadirse cerca del final del manual,
aunque se puede colocar una lista de términos utilizados
frecuentemente al principio.

15. Organizar los Componentes del Manual de Usuario
5. Usar capturas de pantalla: para ilustrar los procedimientos
complejos en los cuales el usuario necesite una confirmación visual
de que esté llevando a cabo los pasos. Ajustar las imágenes a un
tamaño adecuado que permita leer su contenido y encuadre bien en
el manual, de ser necesario se deben separar las imágenes en partes
para mostrar las partes relevantes junto al texto que respaldan. Los
tamaño debe ser consistente, esto hará que las imágenes luzcan más
atractivas para el usuario.

16. Diseñar un Manual de Usuario Legible
1. Fuentes legibles: elegir un número reducido de fuentes que se
vean bien juntas. Las fuentes serif (Times New Roman, Baskerville,
Book Antiqua, …), funcionan mejor en grandes fragmentos de texto
impresos en el cuerpo principal del manual de usuario (tamaño de
10 o 12 puntos). Las fuentes sans serif (Arial, Calibri, Century
Gothic, …), se pueden utilizar en grandes fragmentos de texto en
tamaños de 8 a 10 puntos en un documento impreso o digital. Una
vez elegida las fuentes, crear una página de muestra para verificar
que las fuentes se vean bien juntas en el papel y mostrarle al
usuario para que apruebe la apariencia del manual antes de
continuar escribiéndolo.
2. La distribución: colocar el título del manual o del capítulo en el
encabezado; el número de página (en el encabezado o en el pie de
página), diferenciando la primera página de cada sección o capítulo
de las otras páginas. Destacar el texto de las referencias de las
imágenes que permita leerlo con facilidad. Dejar márgenes
razonablemente.

17. Diseñar un Manual de Usuario Legible
3. Diseñar una plantilla del documento: Muchos procesadores de
texto ofrecen la posibilidad de crear plantillas de documentos para
los manuales de usuario. La mayoría de estos programas también
incluyen un conjunto de plantillas predefinidas que puedes
modificar según lo necesites, en vez de crear la plantilla desde el
comienzo. Estos también ofrecen la posibilidad de crear estilos, que
son tipos y tamaños de fuente predefinidos para los títulos, los pies
de páginas, los encabezados y el cuerpo del texto. Se pueden elegir
uno de los nombres de estilo predefinidos o crearlos. Es
recomendable crear anticipadamente todos los estilos que se
puedan necesitar, así no se detendrá para crearlos mientras estés
escribiendo realmente el manual.

18. DOCUMENTACIÓN DEL SISTEMA
 Es inherentemente técnica, siendo uno de sus componentes
más importante la versión fuente de todos los programas del
sistema.
 Es muy importante que estos programas sean presentados en
formato muy legible; por esta razón se requiere un buen uso
de la sintaxis y de la gramática del lenguaje de programación
de alto nivel, el uso de sentencias comentario adecuadas y en
los puntos notables del código, un diseño modular que
permita a cada módulo ser presentado como una unidad
coherente. Así mismo se requiere seguir convenios de
notación, sangrados en las líneas de programa, establecer
diferencias en la escritura de nombres de variables,
constantes, objetos, clases, etc., y
convenios de documentación que
aseguren que todos los programas
están documentados suficientemente.

19. MANUAL DE MANTENIMIENTO
Documentación para Programadores
Es la documentación requerida para mantener un programa durante
su ciclo de vida.
Constituye el elemento de referencia para el programador que deba
realizar cambios o ampliaciones del programa en el futuro. La
necesidad de mantenimiento deriva de:
• Defectos del programa no detectados y que es necesario corregir.
• Cambios externos de índole políticos, técnicos, sociales, etc., que
afectan al programa (normativas, moneda, actualizaciones del sistema
operativo, etc.)
• Solicitudes de los clientes o usuarios.
El mantenimiento de un programa puede afectar su diseño básico,
funciones importantes desligadas del núcleo del programa o
cuestiones meramente estéticas; de cualquier
forma, el mantenimiento debe considerarse
como programación en todos sus sentidos,
debiendo partir del conocimiento del
problema y avanzar con siguiendo las
normas para una programación sólida.

20. MANUAL DE MANTENIMIENTO
Es ideal un mantenimiento que respete la filosofía y el estilo
original del programa, de modo que un auditor no pudiera
detectar qué parte del programa corresponde al código original y
qué parte a la ampliación o corrección.
Por desgracia esto muchas veces no se cumple, por descuido o
porque simplemente realizar un mantenimiento de calidad puede
ser muy costoso frente a una opción rápida y que funciona. En
ocasiones se renuncia a un mantenimiento de calidad comenzando
un proceso de reparaciones puntuales y rápidas.
Cada reparación introduce un poquito de desorden y dificultad
de seguimiento al programa hasta que se
llega a un punto en que el mantenimiento es
imposible o demasiado costoso. Es el punto
en que se cae la estructura y el obliga a
desistir. Es el momento de hacer una
reestructuración total o incluso empezar una
nueva construcción.

21. MANUAL DE MANTENIMIENTO
El problema surge cuando diversas operaciones de
mantenimiento con distintas formas de construcción y filosofía
empiezan a afectar a la lógica e interconectividad entre las
distintas partes del programa. No hace falta decir que si no se
parte de un programa bien estructurado y documentado el
mantenimiento se complica enormemente.
No se puede decir que realizar un mantenimiento de calidad
sea lo más adecuado: hay ocasiones en que puede interesar un
mantenimiento rápido. El programador habrá de valorar varios
factores, entre otros el tiempo disponible, las perspectivas de
futuro del programa, etc.
Muchos programas de gran
utilidad se pierden porque ya no
existe mantenimiento para
adaptarlos a los avances del
hardware y los sistemas
operativos.

22. MANUAL DE MANTENIMIENTO
Una documentación de mantenimiento completa puede
contener:
 Portada, número de versión, autor, índice.
 Objeto y aspectos principales del programa.
 Diagrama de flujo modular.
 Diagrama de flujo para cada módulo, desarrollado y con
enfoque a las variables y procesos internos.
 Código completo del programa.
 Explicación de la gestión de errores del programa (Plan de
Pruebas).
 Esquema o índice descendente del programa, actualizado.
 Explicación de variables, datos, archivos.
 Recomendaciones para el mantenimiento futuro.
 Cualquier información que se considere relevante para un
programador que haya de trabajar con el programa.

23. OBSERVACIONES GENERALES
 La documentación no debería ser lo último que se haga en
cuanto a la escritura de un programa, es necesario escribirla
desde las primeras etapas del desarrollo del código, pues
cuando se codifica se tiene claro el significado de lo que se
está haciendo y el porqué se hace.
 Se debe finalizar el documento con una breve lista de
 Utilizar comentarios prólogo.
 Una línea de comentario por cada diez líneas de código
ejecutable.
 Los comentarios no deben oscurecer el código.
 Los comentarios deben aportar información adicional, no
parafrasear lo que se escribe en el código.
 Un comentario incorrecto es peor
que la ausencia de comentario.
 Usar espacios en blanco para
incrementar la legibilidad.

24. ACTIVIDADES
 Investigar los buenos hábitos de programación, haciendo
énfasis en las reglas para la documentación internas mientras
se escribe el código fuentes.

25. REFERENCIAS
Corona, M. y Ancona M. 2011.
Diseño de algoritmos y su
codificación en lenguaje C.
McGraw-Hill. México.
Joyanes, L. y Zahonero, I. 2002.
Programación en C. Metodología,
algoritmos y estructura de datos.
McGraw-Hill.
Joyanes, L. 2008. Fundamentos de
Programación, Algoritmos,
Estructura de Datos y Objetos.
Cuarta edición. McGraw-Hill.
López, J. Algoritmos y
Programación. 2009. Segunda
Edición. Eduteka.
Unidad 2:
Estándares de Calidad en el
Diseño de Algoritmos y
Construcción de Programas
2.3.- Documentación