Issuu on Google+

DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Técnicas de Programación.

TÉCNICAS DE PROGRAMACIÓN

Elaborado por: Eduar Olivero

DOCUMENTACIÓN DE CÓDIGO

Documentación de Código. | Eduar Olivero Revisado por: Prof. Luz Grajales

Fecha: 18/03/13


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Documentación de Código Documentar el código de un programa es añadir suficiente información como para explicar lo que hace, punto por punto, de forma que no sólo los ordenadores sepan qué hacer, sino que además los humanos entiendan qué están haciendo y por qué. Entre lo que tiene que hacer un programa y cómo lo hace hay una distancia impresionante: todas las horas que el programador ha dedicado a preparar una solución y escribirla en el lenguaje que corresponda para que el ordenador la ejecute ciegamente. Documentar un programa no es sólo un acto de buen hacer del programador por aquello de dejar la obra rematada. Es además una necesidad que sólo se aprecia en su debida magnitud cuando hay errores que reparar o hay que extender el programa con nuevas capacidades o adaptarlo a un nuevo escenario. Hay dos reglas que no se deben olvidar nunca: 1.

todos los programas tienen errores y descubrirlos sólo es cuestión de tiempo y de que el programa tenga éxito y se utilice frecuentemente. 2. todos los programas sufren modificaciones a lo largo de su vida, al menos todos aquellos que tienen éxito.

Por una u otra razón, todo programa que tenga éxito será modificado en el futuro, bien por el programador original, bien por otro programador que le sustituya. Pensando en esta revisión de código es por lo que es importante que el programa se entienda: para poder repararlo y modificarlo.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Comentario En programación, un comentario es una construcción del lenguaje de programación destinada a incrustar anotaciones legibles al programador en el código fuente de un Programa informático. Estas anotaciones son potencialmente significativas para los programadores, pero usualmente ignorados por los compiladores e intérpretes. Los comentarios son añadidos usualmente con el propósito de hacer el código fuente más fácil de entender con vistas a su mantenimiento o reutilización. La sintaxis y reglas para los comentarios varían y usualmente son definidas en la especificación del lenguaje de programación. Se ha de tener en cuenta que los comentarios necesitan mantenimiento igual que el código y, por tanto, que un comentario preciso y conciso es más fácil de mantener que uno largo, repetitivo y complicado. Los comentarios tienen una amplia gama de posibles usos: desde la mejora del código fuente con descripciones básicas hasta la generación de documentación externa. También se utilizan para la integración con sistemas de control de versiones y otros tipos de herramientas de programación externas. La flexibilidad proporcionada por los comentarios da pie a un amplio abanico de formas de uso distintas y a la inclusión de información inútil dentro del código fuente. Para evitar este inconveniente, muchos programadores y analistas de software adoptan alguna de las "filosofías" o metodologías para la correcta utilización de los comentarios.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Formato Los comentarios adoptan por norma general un formato de "bloque" (también denominado de "prólogo") o de "fin de línea" (también denominado "inline"). Un comentario de bloque delimita una zona del código fuente en la cual es permitido expandirse a varias líneas de texto. Esta región se reconoce por un delimitador de inicio y un delimitador de final del comentario. Algunos lenguajes de programación admiten que los comentarios se aniden recursivamente pero otros lenguajes no lo admiten. Un comentario de fin de línea comienza con un delimitador y continúa hasta el final de la línea de texto (es decir, no es necesario un segundo delimitador). En otros casos, el comentario de fin de línea comienza en una cierta columna dentro del código fuente no siendo necesario un delimitador. Los delimitadores son una secuencia conocida de caracteres y suelen ser distintos para los comentarios de bloque que para los de fin de línea. Por ejemplo, el lenguaje C++ usa, para los comentarios de bloque, los delimitadores /* y */ mientras que los comentarios de fin de línea utiliza el delimitador //. Otros lenguajes solamente admiten un tipo de comentario. Por ejemplo, ADA solamente dispone de comentarios de fin de línea mediante el delimitador --.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Usos Planeación / Revisión: Los comentarios se pueden utilizar como una forma de pseudocódigo para describir la intención antes de escribir el código real. En este caso se debe explicar la lógica detrás del código en lugar del código en sí mismo.

/* itera hacia atrás por todos los elementos retornados por el servidor (estos deben ser procesados cronológicamente)*/ for (i = (numElementsReturned - 1); i >= 0; i--){

/* procesa los datos de cada elemento */ updatePattern(i, returnedElements[i]); } Si se deja este tipo de comentario luego de escribir el código, se simplifica el proceso de revisión al permitir la comparación directa del código con los resultados previstos. Descripción de código: Los comentarios pueden ser utilizados para resumir el código o para explicar la intención del programador. Según esta escuela de pensamiento, re-explicar el código en lenguaje natural se considera superfluo y la necesidad de volver a explicar el código puede ser un signo de que es demasiado complejo y debe ser reescrito. "No documentes mal código – re-escríbelo." "Los buenos comentarios no repiten el código, ni lo explican. Estos aclaran su intención. Los comentarios deben explicar, a un nivel de abstracción más alto que el propio código, lo que se intenta conseguir" Los comentarios también pueden ser utilizados para explicar por qué un bloque de código no se ajusta a las convenciones o las buenas prácticas. Esto está especialmente relacionado con proyectos de escaso tiempo de desarrollo, o en la corrección de errores.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

' Se asigna una segunda variable debido a que se producen errores ' en el servidor cuando se reutilizan los datos del formulario. No se encontró documentación ' sobre el comportamiento extraño del servidor, así que simplemente se codificó para resolverlo. vtx = server.mappath("local settings") Descripción algorítmica: A veces, el código fuente contiene una solución nueva o digna de mencionarse a un problema específico. En tales casos, los comentarios pueden contener una explicación de la metodología. Estas explicaciones pueden incluir diagramas y pruebas matemáticas formales. Esto puede ser la explicación del código, en lugar de una clarificación de sus intenciones, pero otros encargados del mantenimiento del código pueden encontrar como fundamental esta explicación. Esto puede ser especialmente cierto en el caso de problemas de dominios de alta especialización; así como en optimizaciones, construcciones o llamadas a funciones de uso no cotidiano. Por ejemplo, un programador puede agregar un comentario para explicar por qué se eligió un Ordenamiento por inserción en lugar de quicksort, pues el primero es, en teoría, más lento que el segundo. Esto podría escribirse de la siguiente manera: list = [f (b), f (b), f (c), f (d), f (a), ...];

// Se requiere un ordenamiento estable, mientras el desempeño realmente no importa. insertion_sort (list); Inclusión de recursos: Logotipos y diagramas de flujo consistentes en construcciones de arte ASCII pueden ser insertados en el código fuente en forma de comentario. Además, puede incrustarse como comentarios avisos de derechos de autor, fecha de creación, versión del producto, contacto con el propietario y/o creador.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

El fragmento de código que sigue es un simple diagrama ASCII que representa el flujo de proceso para un script de administración de sistemas contenido en un Fichero Windows Script que se ejecuta en Windows Script Host A pesar de que la sección que marca el código aparece como un comentario, el diagrama de hecho aparece en una sección XML CDATA sección, que técnicamente se considera distinta de los comentarios, pero que puede servir para propósitos similares.

<!-- begin: wsf_resource_nodes --> <resource id="ProcessDiagram000"> <![CDATA[ HostApp (Main_process) | V script.wsf (app_cmd) --> ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]> </resource> Depuración: Una práctica común entre programadores es comentar un fragmento de código, es decir, agregar delimitadores de modo que un bloque de código se convierta en un comentario, y por tanto no se ejecutará en el programa final. Esto podría hacerse para excluir algunas piezas del código del programa o, de manera más común, para encontrar la causa de un error. Comentando sistemáticamente y ejecutando partes del programa, la causa del error puede ser determinada, permitiendo su corrección. A continuación un ejemplo de cómo comentar código con el propósito de excluirlo:

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

if (opt.equals ("e")) opt_enabled = true;

/* if (opt.equals ("d")) opt_debug = true; // */ //* if (opt.equals ("v")) opt_verbose = true;

// */ El fragmento de código de arriba sugiere que el programador optó por desactivar la opción de depuración por alguna razón. Este estilo específico de comentario es más adecuado para la depuración. Un carácter de barra simple delante del delimitador de apertura es el que permite habilitar o deshabilitar el comentarios de bloque completo. Muchos EIDs permiten agregar o remover rápidamente este tipo de comentarios con opciones del menú singulares o atajos del teclado. El programador solamente debe marcar la parte de texto que desea comentar o descomentar y elegir la opción apropiada. Esto es particularmente útil con fragmentos grandes de código. Generación de documentación Las herramientas de programación en ocasiones incorporan documentación y metadatos en los comentarios. Estas pueden incluir las posiciones de inserción para la inclusión automática de archivos de cabecera, comandos para configurar el modo de resaltado de sintaxis o el número de revisión del archivo. Estos comentarios de control funcional son también conocidos comúnmente como anotaciones. Mantener la documentación dentro de comentarios en el código fuente es considerado como una forma de simplificar el proceso de documentación, así como un aumento en las posibilidades de que la documentación se mantendrá al día con los cambios en el código.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Habitualmente este tipo de comentarios requiere utilizar una sintaxis básica para que puedan ser interpretados por el generador de documentación a diferencia de los comentarios anteriores donde no necesariamente se debe de utilizar una sintaxis predefinida. Ejemplos de generadores de documentación son el programa javadoc, diseñado para ser utilizado con el lenguaje de programación Java, Ddoc para el lenguaje de programación D y doxygen, para ser usado con C/C++, Java IDL y PHPDoc para PHP. C#, F# y Visual Basic implementan una característica similar llamada comentarios XML, que son leídos por IntelliSense para los ensamblados compilados del entorno.NET. Herramientas para documentar código Javadoc: documentación de APIs El paquete de desarrollo Java incluye una herramienta, javadoc, para generar un conjunto de páginas web a partir de los ficheros de código. Esta herramienta toma en consideración algunos comentarios para generar una documentación bien presentada de clases y componentes de clases (variables y métodos). Aunque javadoc no ayuda a la comprensión de los detalles de código, si ayuda a la comprensión de la arquitectura de la solución, lo que no es poco. Se dice que javadoc se centra en la interfaz (API - Application Programming Interface) de las clases y paquetes Java. Javadoc realza algunos comentarios, de los que exige una sintaxis especial. Deben comenzar por "/**" y terminar por "*/", incluyendo una descripción y algunas etiquetas especiales.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Doxygen: Es un programa que analiza el código en busca de directivas en forma de comentarios y las transforma en documentación, bien HTML, bien LaTeX e incluso podemos crear una página de manual de linux para visualizar con el mítico comando "man". Doxygen acepta multitud de lenguajes como C/C++ o Java. La principal ventaja de Doxygen es sin duda que las directivas no son más que comentarios de forma que no tenemos que crear una documentación aparte, sino, simplemente, comentar el código.

Estilos Hay muchas alternativas cuando se considera como los comentarios deben aparecer en el código fuente. Para grandes proyectos, los estilos de los comentarios se agregan apenas comienzan el proyecto. Normalmente los programadores prefieren estilos que son consistentes, no obstructivos, fáciles de modificar, y difíciles de romper. Los siguientes fragmentos de código en C son solo un ejemplo de como los comentarios pueden variar de estilo, mientras todos contienen la misma información básica:

/* Este es el cuerpo del comentario. Variante 1 */ /***********************************\ ** * Este es el cuerpo del comentario. * * Variante 2. * ** \************************************/

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Factores tales como la preferencia personal, la flexibilidad de las herramientas de programación, y otras consideraciones tienden a influir en las variantes de estilo utilizado en el código fuente. Etiquetas Algunas etiquetas se utilizan en los comentarios para ayudar en la indexación de los problemas comunes. Tales etiquetas son comúnmente resaltadas de sintaxis y permite búsquedas con herramientas de programación común, como la utilidad grep de UNIX. Ejemplos de convenios etiqueta son: FIXME: para marcar código problemático potencial que requiere una atención especial y/o revisión. NOTE: peligros potenciales para documentar el funcionamiento interno del código y de indicar. TODO: para indicar las mejoras planificadas. XXX: para advertir a otros programadores de código problemático o equivoco. Existe el riesgo de que las etiquetas se acumulen con el tiempo, es conveniente incluir la fecha y el propietario de etiqueta en el comentario de etiquetas para facilitar el seguimiento.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

13 Consejos para comentar tu código

1. Comenta a varios niveles Comenta los distintos bloques de los que se compone tu código, aplicando un criterio uniforme y distinto para cada nivel. Puedes, por ejemplo, seguir un modelo como: • •

En cada clase, incluir una breve descripción, su autor y fecha de última modificación Por cada método, una descripción de su objeto y funcionalidades, así como de los parámetros y resultados obtenidos

En realidad, lo importante es ceñirse a unas normas (comúnmente aceptadas si se trata de trabajo en equipo) y aplicarlas siempre. Las reglas concretas pueden ser elegidas a la conveniencia de cada cual. Obviamente, una solución bastante aceptable e incluso aconsejable es utilizar las convenciones y herramientas que ayudan y facilitan esta tarea.

2. Usa párrafos comentados Como complemento al punto anterior, es recomendable dividir un bloque de código extenso en "párrafos" que realicen una tarea simple, e introducir un comentario al principio de forma que se guíe al lector, precediéndolos, además, de una línea en blanco que ayude a separar cada uno del anterior.

3. Tabula por igual los comentarios de líneas consecutivas Si tenemos un bloque de líneas de código donde existe por cada una de ellas un comentario, es buena costumbre tabularlos todos a la misma posición, de forma que quedarán alineados y serán más sencillos de leer, sobre todo si forman parte de la misma frase. Ojo a las tabulaciones. Hay editores que usan el carácter ASCII (9) y otros, en cambio, lo sustituyen por un número determinado de espacios, que suelen variar según las preferencias personales Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

del desarrollador. Lo mejor es usar espacios simples o asegurarse de que esto es lo que hace el IDE correspondiente.

4. No insultes la inteligencia del lector Debemos evitar comentarios absurdos como: if (a == 5)

// Si a vale cinco, ...

counter = 0; // ... ponemos el contador a cero Este exceso necesita mucho tiempo a la hora de su creación, lo necesitará para su mantenimiento y, además, la mayoría de las veces distraerá al lector con detalles que no es necesario conocer o que pueden ser deducidos echando un vistazo al código.

5. Sé correcto Evita comentarios del tipo "ahora compruebo que el estúpido usuario no haya introducido un número negativo", o "este parche corrige el efecto colateral producido por la patética implementación del inepto desarrollador inicial". El uso de este tipo de comentarios no dice nada a favor de su creador, y, además, nunca se sabe quién los va a leer en el futuro. Emarts, en "Sapos, culebras y código fuente" muestra ejemplos de comentarios de este tipo. Otro tema relacionado igualmente importante: cuida la ortografía. El hecho de que los comentarios no se vean desde el exterior no implica que puedas descuidarlos. Una ortografía correcta mejora la calidad de la expresión escrita y, por tanto, de la comunicación, que es de lo que se trata. 6. No pierdas el tiempo No comentes si no es necesario, no escribas nada más que lo que necesites para transmitir la idea. Nada de diseños realizados a base de caracteres ASCII, ni florituras, ni chistes, ni poesías, ni chascarrillos. Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

En resumen, mantén los comentarios simples y directos, pues de lo contrario harás perder tiempo a tu sucesor. 7. Utiliza un estilo consistente Hay quien opina que los comentarios deberían ser escritos para que los entendieran no programadores. Otros, en cambio, piensan que debe servir de ayuda para desarrolladores exclusivamente. En cualquier caso, coincidiendo con Ryan Campbell en su post Successful Strategies for Commenting Code, lo que importa es que siempre sea de la misma forma, orientados al mismo destinatario. Personalmente, dudo mucho que alguien de un perfil alejado a la programación vaya a acercarse al código, por lo que, para mi gusto, bastaría con cubrir el segundo caso de los expuestos anteriormente. 8. Para los comentarios internos usa marcas especiales Y sobre todo, aunque no únicamente, cuando se trabaja en un equipo de programación en el que varias personas pueden estar tocando las mismas porciones de código. En este caso los comentarios no se usan para explicar una porción de código, sino para realizar anotaciones sobre el mismo a las que hay que prestar especial atención. Eso sí, si usas esta técnica, recuerda que debes actualizarlos conforme las anotaciones dejen de tener sentido. 9. Comenta mientras programas Ve introduciendo los comentarios conforme vas codificando. No lo dejes para el final, puesto que entonces te costará más del doble de tiempo, si es que llegas a hacerlo. Olvida las posturas "no tengo tiempo de comentar, voy muy apurado", "el proyecto va muy retrasado"... son simplemente excusas. Si tu intención es comentar el código, no te engañes y ¡hazlo! Hay incluso quien opina que los comentarios que describen un bloque deberían escribirse antes de codificarlo, de forma que, en primer lugar, sirvan como Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

referencia para saber qué es lo que hay que hacer y, segundo, que una vez codificado éstos queden como comentarios para la posteridad. 10. Comenta como si fuera para ti mismo. De hecho, lo es. A la hora de comentar no pienses sólo en mantenimiento posterior, ni creas que es un regalo que dejas para la posteridad del que sólo obtendrá beneficios el desarrollador que en el futuro sea designado para corregir o mantener tu código. En palabras del genial Phil Haack, "tan pronto como una línea de código sale de la pantalla y volvemos a ella, estamos en modo mantenimiento de la misma" Como consecuencia, nosotros mismos seremos los primeros beneficiaros (o víctimas) de nuestro buen (o mal) hacer. 11. Actualiza los comentarios a la vez que el código De nada sirve comentar correctamente una porción de código si en cuanto éste es modificado no se actualizan también los comentarios. Ambos deben evolucionar paralelamente, pues de lo contrario estaremos haciendo más difícil la vida del desarrollador que tenga que mantener el software, al facilitarle pistas incorrectas para comprenderlo. Atención especial a las refactorizaciones automáticas, que suelen introducir cambios en distintos puntos del código de un proyecto, dejando los comentarios obsoletos en ese mismo instante. 12. La regla de oro del código legible He dejado para el final uno de los principios básicos para muchos desarrolladores: deja que tu código hable por sí mismo. Aunque se sospecha que este movimiento está liderado por programadores a los que no les gusta comentar su código ;-), es totalmente cierto que una codificación limpia puede hacer innecesaria la introducción de textos explicativos adicionales. Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Recordemos, por ejemplo, el código introducido en el post "Interfaces fluidos (fluent interfaces)", donde se muestra lo que esta técnica puede aportar a la claridad y autoexplicación en un desarrollo: Console.WriteLine("Resultado: " + new Calculator() .Set(0) .Add(10) .Multiply(2) .Substract(4) .Get() ); A la vista del ejemplo, ¿es necesario añadir algún comentario para que se entienda qué hace el código? El uso de nombres apropiados (aconsejo leer el clásico Ottinger's Rules), indentación correcta y la adopción de guías de estilo (podéis ver algunas en la wikipedia, o googleando un poco) facilitan enormemente la escritura homogénea e inteligibilidad directa del código. El no cumplimiento de esta regla hace que a veces los comentarios puedan parecer una forma de pedir perdón al desarrollador que se encargará del mantenimiento del software. 13. Difunde estas prácticas entre tus colegas Obviamente, aunque ya hemos comentado en el punto 10 que nosotros mismos nos beneficiamos inmediatamente de las bondades de nuestro código comentado, la generalización y racionalización de los comentarios y la creación código claro nos favorecerá a todos, y sobre todo en contextos de trabajo en equipo. No dudes, por tanto, en crear cultura de comentarios en tu entorno.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Manuales 1) Manuales Del usuario Expone los procesos que el usuario puede realizar con el sistema implantado. Para lograr esto, es necesario que se detallen todas y cada una de las características que tienen los programas y la forma de acceder e introducir información. Permite a los usuarios conocer el detalle de qué actividades ellos deberán desarrollar para la consecución de los objetivos del sistema. Reúne la información, normas y documentación necesaria para que el usuario conozca y utilice adecuadamente la aplicación desarrollada. Objetivos -Que el usuario conozca cómo preparar los datos de entrada. -Que el usuario aprenda a obtener los resultados y los datos de salida. -Servir como manual de aprendizaje. -Servir como manual de referencia. -Definir las funciones que debe realizar el usuario. -Informar al usuario de la respuesta a cada mensaje de error. Pasos a seguir para definir como desarrollar el manual de usuario. Identificar los usuarios del sistema: personal que se relacionará con el sistema. Definir los diferentes tipos de usuarios: se presentan los diferentes tipos de usuarios que usarían el sistema. Ejemplo: usuarios directos, indirectos. Definir los módulos en que cada usuario participará: Se describen los módulos o procesos que se ejecutarán por cada usuario en forma narrativa breve y clara. Importancia Del Manual De Usuario El Manual de Usuario facilita el conocimiento de: -Los documentos a los que se puede dar entrada por computadora. -Los formatos de los documentos. -Las operaciones que utiliza de entrada y salida de los datos. -El orden del tratamiento de la computadora con los datos introducidos. Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

-El momento en que se debe solicitar una operación deseada. -Los resultados de las operaciones realizadas a partir de los datos introducidos. Al elaborar el Manual de Usuario, hay que tener en cuenta a quién va dirigido es decir, el manual puede ser manejado desde el director de la empresa hasta el introductor de datos. Por consiguiente, debe redactarse de forma clara y sencilla para que lo entienda cualquier tipo de usuario. Contenido Diagrama general del sistema Muestra en forma condensada el flujo general de la información y de las actividades que se realizan en el sistema. Proporciona una visión general del sistema. Representar los diagramas utilizando para ello diagramas de bloques. Diagrama particular detallado. Presentar gráficamente todos los pasos que se efectúen dentro del departamento usuario a quien está dirigido este manual. Deben especificarse los archivos de entrada, salida, los resultados, revisiones y procesos manuales. Explicación Genérica De Las Fases Del Sistema En este punto se explica en forma específica y detallada todas las operaciones que aparecen representadas en forma gráfica en el diagrama particular. Se analizan cada una de las fases señalando: -El proceso principal que se desarrolla. -La entrada de la información. -La obtención de un resultado parcial. -El envío de información a otra dependencia. Instalación Del Sistema La instalación del sistema proporciona detalles completos sobre la forma de instalar el sistema en un ambiente particular. Elaborado por: Revisado por: Eduar Olivero Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Iniciación Al Uso Del Sistema En este punto se explica cómo iniciarse en el sistema y cómo se pueden utilizar sus cualidades comunes. Esta documentación debe decir al usuario cómo salir de un problema cuando las cosas funcionan mal. 2) Manual De Referencia Es el documento definitivo de cara al usuario y debe ser completo. Describe con detalle las cualidades del sistema y su uso, los informes de error generados y las situaciones en que surgen esos errores. Dependiendo del sistema, los documentos al usuario se pueden proporcionar por separado o reunidos en varios volúmenes. Los sistemas de ayuda en línea evitan que el usuario pierda tiempo en consultas manuales. Caducidad De Documento Fuente Y Destino Final Como el usuario trabajará con documentos fuentes, éstos podrán tener un período de retención y un destino especificado. 3) Manual de captación Permite tener una clara visión del proceso de Captación de los latos fuentes previo al procesamiento electrónico de los mismos. Objetivos Documentar al usuario a cerca del recorrido a través de las pantallas del sistema. Conocer la forma cómo el usuario puede utilizar el equipo necesario para la ejecución del sistema.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

Contenido Diagrama General Del Sistema Este diagrama debe ser presentado gráficamente y en forma sencilla. Representar los diagramas utilizando para ello diagramas de bloques (es el mismo diagrama que se presenta en el Manual Administrativo). Diagramas De Pantalla Presentar en este punto el flujo del sistema en las pantallas utilizadas por cada módulo. Puntos a documentar en una pantalla: -Explicación del recorrido para llegar a la pantalla. -Formato de los datos a captar. -Formato en que son captados los datos. -Explicación Genérica De Las Fases Del Sistema -Es una explicación clara, breve de todos los módulos que se presentan en el diagrama -general. -Equipo Utilizado Para La Captación -Se debe crear un instructivo que permita al usuario el entrenamiento del sistema. Debe contener los siguientes puntos: Uso del equipo: Describir detalladamente el uso correcto del equipo utilizado para la captación de la información, dando una explicación del encendido, manejo, control y del material que se usa como medio de captación de los datos. Caducidad De Documentos Fuentes Establecer por escrito la fecha de caducidad de los documentos fuentes, el fin a que han de destinarse ya sea para su destrucción, devolución o conservación en un archivo. Elaborado por: Revisado por: Eduar Olivero Prof. Luz Grajales


DOCUMENTACIÓN DE CÓDIGO Universidad Nueva Esparta

Fecha: 18/03/13

Técnicas de Programación.

4) Manual de operación Objetivo Contiene la información que permite al personal de operación utilizar en forma eficiente la operación de los sistemas de procesamiento electrónico. Contenido Diagrama general del sistema Este diagrama debe ser presentado gráficamente y en forma sencilla. Representar los diagramas utilizando para ello diagramas de bloques (es el mismo diagrama que se presenta en el Manual Administrativo). Diagrama general del flujo del proceso electrónico. Se representa en este diagrama todo el ambiente periférico que interactúa en el sistema en cuanto a: entradas manuales, medios magnéticos y dispositivos de salida. La simbología a utilizar debe ser establecida como estándar. (Ejemplos: cintas, discos, disquetes). Explicación Genérica De Las Fases Del Sistema Es una explicación clara, breve de todos los módulos que se presentan en el Diagrama general descrito anteriormente.

Elaborado por: Eduar Olivero

Revisado por: Prof. Luz Grajales


documentacion de codigo