Este documento describe los diferentes tipos de documentación que deben incluirse para un programa de software, incluyendo comentarios internos, documentación externa para usuarios, documentación técnica del sistema y manuales de mantenimiento. Explica que la documentación debe escribirse desde las primeras etapas del desarrollo y debe proporcionar información útil sin oscurecer el código subyacente.

1. Unidad 2:
Estándares de Calidad
en el Diseño de
Algoritmos y
Construcción de
Programas
Alumno:Richard Alcantara

2. 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.
Documentación interna Documentación externa

3. Comentarios de prologo
Prólogo: son de los comentarios que acompañan a cada
subprogramas (rutinas):
allí encontramos información sobre :
• 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.).

4. Comentario de directorio
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 información como:
• Autor.
• Fecha.
• el Proyecto del que forma parte el fichero:
Rutinas contenidas y su finalidad

5. comentarios explicatorios
 se utilizan para aportar información adicional en ciertos
puntos del código. 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.

6. DOCUMENTACIÓN EXTERNA
No forma parte del programa fuente, es un manual que
acompaña al programa.
Entre la documentación externa encontramos la:
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

7. 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.

8. MANUAL DE MANTENIMIENTO
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.

9. OBSERVACIONES GENERALES
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.