UNIVERSIDAD DE EL SALVADOR

FACULTAD DE INGENIERÍA Y ARQUITECTURA

ESCUELA DE INGENIERÍA DE SISTEMAS INFORMÁTICOS

PROGRAMACIÓN I

UNIDAD II
DOCUMENTACIÓN DE ALGORITMOS (PROGRAMAS)

Objetivo: Conocer en qué consiste la Técnica de Documentación y su importancia en el diseño

de algoritmos, para iniciar a aplicarla después en nuestras soluciones de problemas.

Contenido:
• Introducción 1
• Documentación de Algoritmos 1
• Importancia de Documentación 2
• Clasificación de la Documentación

Introducción
Los algoritmos o programas que diseñamos la mayoría de veces los hacemos para otras
personas; es decir, son utilizados por otras personas y no por quien los escribió. Por ejemplo,
quien diseñó el programa para calcular el salario a los empleados de una empresa, generalmente
no es el que imprime las planillas; el que diseña el programa para facturarle a un cliente de un
almacén no es el que generalmente factura, etc.

Por esta razón, los algoritmos (o programas) deben ser fáciles de utilizar, debido a que la mayoría
de las veces quien utiliza el programa no tiene nociones de programación además, de que, quien
les da mantenimiento puede ser otro programador. En los siguientes ejemplos se evidencia esta
necesidad de escribir programas fáciles de utilizar:

El usuario tiene que saber, que tipo de datos introducir, en qué momento hacerlo y cuantos
datos introducir.

En el caso de las salidas de datos, el usuario o quien lee estos reportes, debe saber que
representa esa información.

Además para darle el mantenimiento necesario al algoritmo, se necesita saber que hace, y
como lo hace.

En este sentido, debemos recordar que nuestros algoritmos deben ser lo más claros y explícitos
posibles, para que otra persona, trabaje, modifique o califique nuestro trabajo.

La Documentación de algoritmos, es la parte de la Programación Estructurada que se encarga de

escribir la ‘literatura’ necesaria para comprender perfectamente un algoritmo.

Consiste en escribir detalladamente todo lo que se necesita conocer para trabajar con él y
modificarlo por mantenimiento, cuando sea requerido. Por ejemplo:

1
♦ ¿Qué hace el (Salida de datos) ♦ ¿Cómo lo hace? (Procesamiento
algoritmo? de datos)

♦ ¿Qué necesita para ♦ ¿Qué tipo de ♦ ¿Cuántos? (Entrada de

funcionar? datos necesita? datos)
(hardware y software)

♦ ¿Se divide en partes o ♦ ¿Cuántos ♦ ¿Qué hace o (Salida de

módulos? módulos son? genera cada datos
uno?

♦ ¿Quién lo hizo? ♦ ¿Cuándo lo ♦ ¿Para quién?, (Información

hizo? etc. general)

Debemos recordar conceptos ya conocidos:

ALGORITMO: Serie de pasos que resuelven un problema.

PROGRAMA: Algoritmo escrito en un lenguaje de programación,

PROGRAMADOR: Persona que diseña un algoritmo (flujograma o pseudo código) y lo traduce

o escribe en un lenguaje de programación, en nuestro caso utilizamos C.

USUARIO: Persona que utiliza un programa, no necesariamente escrito por él.

♦ Como ya se dijo, los programas o algoritmos son diseñados, muchas veces, para que otras
personas, usuarios, lo utilicen, por ejemplo los algoritmos que ustedes como estudiantes
diseñan, los utilizamos los profesores al revisarlos y calificarlos. La mayoría de veces los
usuarios no tienen los conocimientos necesarios (matemáticos o de programación) lo que
dificulta la utilización del algoritmo, es aquí donde radica la importancia y aplicación de la
Documentación

El programador debe indicar al usuario como trabajar con el algoritmo, con las indicaciones
siguientes:

Cuando introducir datos, qué tipo de datos, cuántos datos necesita introducir;

Si el proceso que realiza el programa toma un tiempo considerable (más de un minuto)

debe indicarle al usuario, por medio de una impresión que el programa está trabajando
y que presentará los resultados en un momento.

♦ El mantenimiento de un programa, también se facilita mediante la Documentación, ya que,

generalmente esta tarea le corresponde realizarla a alguien que no diseñó el programa.
Gracias a la Documentación podemos saber que variables se utilizan en el programa, que
estructuras lógicas de control se han utilizado y así modificar la lógica del programa para que
éste siga funcionando y produzca la información requerida y correcta.
♦ Los programas de aplicación que nosotros diseñamos, necesitan de cierto hardware y software
para instalarlos y que se puedan utilizar. Estos requerimientos de equipo (capacidad de

2
 memoria RAM, impresor, etc.) y software (sistema operativo, compilador, etc.) se detallan en la
Documentación del programa.

Ahora que ya tenemos una idea de lo que es Documentación de un programa y la importancia de

su utilización, vamos a dividirla en dos categorías:

1. DOCUMENTACIÓN INTERNA:
Es la que escribimos dentro del programa en forma de mensajes. Podemos incluir
comentarios como:

Nombre del Programador.

Fecha en que se diseñó el programa

Tipo de datos que necesita el programa en el momento en que la ejecución del mismo
lo requiera.

Aclaración o ampliación de los datos de salida cuando sean mostrados al usuario, ya
sea en el monitor o en el impresor.

Qué hace una parte del programa (o módulo) del mismo.

Para estos comentarios o mensajes a nivel de flujograma utilizamos 3 símbolos

Comentarios Impresión en Salida en pantalla,

papel monitor

3
Ejemplos:
a. Comentarios internos del algoritmo que no se ejecutan

Inicio
Este flujograma calcula la
edad promedio de 5 personas

Cálculo de la sumatoria
de las edades. Este es un
mensaje muy largo

Fin

En el lenguaje C los comentarios podemos hacerlos de dos formas:

Comentarios de una sola línea, se necesita utilizar el separador //, el comentario termina
con la línea. El primer comentario del flujograma anterior:

// Este programa calcula la edad promedio de 5 personas

Comentarios de más de una línea, en este caso usamos /*, para iniciar el mensaje, y */
para terminarlo; El segundo comentario del diagrama anterior puede escribirse así:
/* Calculo de la sumatoria
de las edades. Este es un
mensaje muy largo*/

4
 b. Documentación de Entradas y Salidas de datos

Entrada de datos Salida de datos

documentada documentada

“Digite la
edad de
la “La edad promedio
persona” es:”, prom, “años”

edad

Es INCORRECTO Una salida como la que sigue

dibujarlo así: no es muy informativa:
INCORRECTO dibujarlo así:

prom
“Edad de la
persona”, edad

Los comentarios en un programa se deben escribir cuando se consideren necesarios, si se

documenta cada paso o línea del programa tendremos dos versiones del algoritmo en un solo
programa el codificado y el narrado, lo cual vuelve tediosa y difícil la lectura del programa.

2. DOCUMENTACIÓN EXTERNA:
Está formada por todos los documentos escritos, que están fuera del programa, para utilizarlo
correctamente, entre los cuales podemos mencionar:

Manual del Usuario: Este documento sirve de guía sobre el uso del programa. Debe ser
escrito para que cualquier usuario, principiante o avanzado, lo comprenda fácilmente. Y
debe contener lo siguiente:
1. Índice
2. Un prefacio, con información sobre cómo usar el propio manual.
3. Una guía rápida sobre cómo usar las funciones principales del programa o sistema.
4. Una sección para la resolución de problemas.
5. Una sección de preguntas formuladas frecuentemente (FAQ)
6. Información de contacto.
7. Un glosario.

Manual de Instalación

5
 Antes de proceder a la instalación en sí, es conveniente tener un conocimiento de los
requisitos de hardware y software para instalar y usar el programa (o más adelante sistema
de información). Este Manual está dirigido al personal técnico responsable de instalar y
configurar inicialmente un sistema de información. Así, este manual se puede dividir en
tres partes:
 Requisitos de hardware y software: Características del hardware y software básico y/o
de aplicaciones, necesarios para hacer la instalación y la utilización del programa (o
sistema).
 Instalación: Detalla paso a paso el proceso de instalación del sistema, en nuestro caso
el programa.
 Configuración: Explica los principales parámetros que deben inicializarse antes de usar
el sistema o programa por el momento (por ejemplo, idioma, hora, fecha, formatos de
texto, etc.).

Manual Técnico
Ya que este manual está dirigido al personal técnico responsable de corregir errores, y
agregar o modificar funciones en el sistema, debe incluir la documentación generada
durante el análisis y diseño del sistema. Estos documentos describen:
 La función del sistema mediante diagramas y descripciones breves de las
actividades principales. (Diagramas de flujo en nuestro caso)
 Los datos, las relaciones entre los datos, las relaciones entre datos y funciones del
sistema. (Análisis del problema, por el momento)

Manual de Implementación
Incluye la descripción de todas las actividades necesarias para convertir un sistema
anterior a otro nuevo sistema. Un sistema de información podría necesitar ser actualizado
o sustituido en forma total por un nuevo sistema. Entre las actividades que debe incluir
están:
• Cambiar software existente,
• Preparar o convertir datos existentes,
• Adquirir equipo informático (hardware y/o software),
• Hacer cambios físicos al edificio o ambiente donde se ubicará el sistema,
• Capacitar o reasignar al personal que operará el sistema,
• Cambiar procedimientos y métodos de trabajo, y
• Garantizar la seguridad de los equipos y datos del sistema.

Manual del Administrador

Instructivo dirigido al responsable de instalar, configurar y administrar un sistema de
información. Ya que el administrador es el encargado de instalar, controlar los accesos,
poner en funcionamiento y, crear o modificar la configuración del sistema, capacitar sobre
el uso del sistema, y solucionar problemas técnicos; el manual debe contener la
información necesaria para realizar dichas actividades.

Los manuales detallados anteriormente, se relacionan con un sistema de información y no con

programas como los que nosotros diseñamos en esta asignatura; por lo tanto, durante este ciclo la
Documentación Externa de nuestras soluciones (algoritmos) estará formada por :

El planteamiento del problema

6

El análisis del problema: Definición de:
1. Variables de Salida
2. Variables de Entrada
3. Restricciones para datos de Entrada
4. Proceso matemáticos
5. Procesos lógicos
6. Variables de proceso.

El flujograma mismo, con los comentarios necesarios

Al utilizar el Análisis Estructurado la documentación anterior debe generarse para cada módulo.

Por eso la insistencia, desde Introducción a la Informática de realizar correctamente y con mucho
cuidado el ANÁLISIS DEL PROBLEMA, ya que además de facilitarnos el diseño del algoritmo,
sirve de documentación Externa del futuro programa.

Material revisado por Ings: Milagro Castillo P.

y Carolina Ayala Ciclo II 2011