Cmo documentar un sistema de software

Un sistema pobremente documentado carece de valor aunque haya funcionado bien en alguna ocasin. En el caso de programas pequeos y poco importantes que slo se utilizan durante un corto periodo de tiempo, unos cuantos comentarios en el cdigo podran ser suficientes. No obstante, la mayora de los programas cuya nica documentacin es el cdigo, se quedan obsoletos rpidamente y es imposible mantenerlos. El que la dedicacin de un poco de esfuerzo a la documentacin sea recompensado incluso dentro de los lmites de un pequeo proyecto, constituye una sorpresa para la mayora de los novatos.

A menos que usted sea infalible y viva en un mundo en el que nada cambia, tendr que volver a consultar el cdigo que ya est escrito, y pondr en duda decisiones que tom durante el desarrollo del mismo. Si no documenta sus decisiones, se ver siempre cometiendo los mismos errores y tratando de comprender lo que pudo haber descrito fcilmente en una ocasin. La falta de documentacin no slo genera trabajo adicional, sino que tambin tiende a daar la calidad del cdigo. Si no posee una ntida caracterizacin del problema, es imposible que desarrolle una solucin clara.

Aprender a documentar software es una tarea complicada y exige un criterio de ingeniera maduro. Documentar de forma concisa es un error habitual, pero el otro extremo puede resultar igual de perjudicial: si escribe documentaciones extensas, stas atosigarn al lector y constituirn una carga a la hora de conservarlas. Es esencial documentar slo los asuntoscorrectos. La documentacin no sirve de ayuda para nadie si su extensin desanima a la gente a la hora de leerla.

Los principiantes tienen la tentacin de centrar sus esfuerzos en temas sencillos, ya que stos les resultan ms fciles de documentar. Esto es una prdida de tiempo; no se aprende nada del esfuerzo y se termina escribiendo una documentacin que es cualquier cosa excepto til. Los principiantes tambin tienden a mostrarse reacios con los problemas de documentacin. Esto trae consigo poca visin de futuro: si usted sabe que algn aspecto de su diseo no es del todo correcto, que alguna parte del problema no se ha aclarado o que es posible que parte del cdigo tenga errores, dgalo! Har que el lector ahorre tiempo dndole vueltas a algo que aparentemente es errneo, se acordar de dnde tiene que mirar si encuentra problemas y acabar teniendo una documentacin ms til y honesta.

Puede cortar y pegar en su documentacin el texto de cualquiera de los boletines que le hemos facilitado. En concreto, es posible que quiera usar partes del boletn de problemas para describir los requisitos. No obstante, asegrese de indicar claramente cualquier cambio que realice, para que su ayudante tcnico no tenga que emular manualmente el programadiffde Unix!

Esquema

Su documentacin debera tener la siguiente estructura. Se facilita un nmero de pginas orientativo, tpico de un proyecto 6.170; lo que presentamos a continuacin son directrices,no un requisito.

1. Requisitos

La seccin de requisitos describe el problema que se est solventando junto con la solucin. Esta seccin de la documentacin resulta interesante tanto para los usuarios como para los implementadores; no debera contener detalles sobre la estrategia de implementacin en concreto. Las otras partes de la documentacin del sistema no sern de inters para los usuarios, nicamente para los implementadores, los encargados del mantenimiento y dems personal.

1. Visin general (hasta 1 pgina)Una explicacin del objetivodel sistema y de la funcionalidad del mismo.

2. Especificacin revisada.Si le facilitaron especificaciones detalladas del comportamiento del sistema, es probable que encuentre que ciertas partes del mismo se encuentran infraespecificadas o son ambiguas. En esta seccin debera aclarar tanto cualquier suposicin que haya hecho sobre el significado de los requisitos, como cualquier extensin o modificacin de los mismos.

3. Manual de usuario (1 - 5 pginas).Una descripcin detallada sobre cmo el usuario puede utilizar el sistema, qu operaciones puede llevar a cabo, cules son los argumentos de la lnea de comando, etc. Las especificaciones detalladas de los formatos deberan relegarse al Apndice. Cualquier suposicin relativa al entorno debera explicitarse aqu: por ejemplo, observe si el programa slo se ejecuta en ciertas plataformas, si supone que la jerarqua de un cierto directorio est presente, si existen otras aplicaciones, etc. Junto con la visin general, este manual debera proporcionar toda la informacin que un usuario del sistema necesita.

4. Funcionamiento (1/2 pgina).Qu recursos necesita el sistema para una operacin normal y qu espacio y tiempo se espera que consuma?

5. Anlisis del problema (2 - 10 pginas).Una descripcin clara del problema subyacente. Esto incluye el modelo conceptual que hay detrs del diseo (y posiblemente la interfaz de usuario), si no se ha tratado ya. El anlisis del problema generalmente incluye uno o msmodelos de objeto del problema,definiciones de sus conjuntos y relaciones y una discusin de asuntos complicados.Los objetos en los modelos de objeto del problemaproceden del dominio del problema, no del cdigo. Los modelos de objeto deberan incluir tanto diagramas como cualquier restriccin textual fundamental, y deberan estar claramente expuestos para una correcta legibilidad. Esta parte tambin debera describir alternativas que hayan sido consideradas pero que se han rechazado, con razones, asuntos no resueltos o aspectos que no hayan sido totalmente aclarados y que vayan a solventarse ms tarde.

Puede que loscasos de usole resulten tiles cuando escriba la especificacin revisada y/o el manual de usuario. Un caso de uso es un objetivo especfico y una lista de acciones que un usuario lleva a cabo para conseguir dicho objetivo. Un cliente puede, entre otras cosas, examinar la lista de acciones para decidir si la interfaz de usuario es aceptable. Si la coleccin de casos de uso abarca todos los objetivos deseados por el usuario, el cliente puede tener la seguridad de que el sistema cumplir con su objetivo.

2. Diseo

La seccin de diseo de su documentacin proporciona un cuadro de alto nivel de su estrategia de implementacin.

1. Visin general (1/2 - 3 pginas).Una visin general del diseo: organizacin de alto nivel, cuestiones de diseo especialmente interesantes, uso de libreras y otros mdulos de terceros e indicadores de aspectos no resueltos o proclives al cambio. Tambin incluye problemas con el diseo: decisiones que pueden resultar errneas y los anlisis de las consecuencias entre la flexibilidad y el funcionamiento que pueden ser juzgadas negativamente.

2. Estructura en tiempo de ejecucin (1 - 5 pginas).Una descripcin de la estructura del estado del programa en ejecucin, expresada comoun modelo de objeto de cdigo.ste debera ocultar las representaciones de los tipos de datos abstractos; su propsito consiste en mostrar las relaciones entre objetos. Los modelos de objeto deberan incluir tanto diagramas como cualquier restriccin textual fundamental, y deberan estar claramente expuestos para una correcta legibilidad. Las representaciones de los tipos de datos deberan explicarse (con sus funciones de abstraccin e invariantes de representacin) si esas representaciones son poco comunes, especialmente complejas o decisivas para el diseo global. Observe que las funciones de abstraccin y losinvariantes de representacin deberan aparecer an as en su sitio normal en el propio cdigo.

3. Estructura del mdulo (1 - 5 pginas).Una descripcin de la estructura sintctica del texto del programa, expresada como un diagrama de dependencia entre mdulos. Debera incluir la estructura del paquete y mostrar tanto las interfaces de Java del programa, calendario, material de clase, trabajos, exmenes, lecturas obligatorias, otras fuentes, prcticas, presentaciones, herramientas y proyectos, como las clases. No es necesario exhibir las dependencias de las clases en la API de Java del programa, calendario, material de clase, trabajos, exmenes, lecturas obligatorias, otras fuentes, prcticas, presentaciones, herramientas y proyectos. SuMDD(diagrama de dependencia entre mdulos) debera estar claramente expuesto para una correcta legibilidad. Explique por qu se eligi esa estructura sintctica en particular (ej.: introduccin de interfaces para el desacoplamiento: qu desacoplan y por qu), y cmo se utilizaron los patrones de diseo concretos.

Para explicar la descomposicin y otras decisiones de diseo, exponga que aportan simplicidad, extensibilidad (facilidad para aadir caractersticas nuevas), particionalidad (los distintos miembros del equipo pueden trabajar en las diferentes partes del diseo sin necesidad de mantener una comunicacin constante) u objetivos similares relativos a la ingeniera de software.

3. Pruebas

La seccin de pruebas de su documentacin indica el enfoque que usted ha elegido para verificar y validar su sistema. (En un sistema real, esto podra incluir tanto las pruebas de usuario para determinar la idoneidad del sistema como solucin al problema descrito en la seccin de requisitos, como la ejecucin desuitesde prueba para verificar la correccin algortmica del cdigo). Del mismo modo que no debera comunicar el diseo de su sistema presentando el cdigo o incluso enumerando las clases, no debera nicamente enumerar las pruebas realizadas. En vez de hacer esto, explique cmo se seleccionaron las pruebas, por qu stas bastaron, por qu un lector debera creer que no se ha omitido ninguna prueba importante y por qu debera creer que el sistema realmente funcionar como se desee cuando se ponga en prctica.

1. Estrategia (1 - 2 pginas).Una explicacin de la estrategia general de las pruebas:blackboxy/oglassbox,top down(de arriba hacia abajo) y/obottom up(de abajo hacia arriba), tipos detest beds(bancos de prueba) y manejadores de tests que se han utilizado, fuentes de datos del test,suitesde prueba, mtrica de cobertura, comprobacin en tiempo de compilacin frente a sentencias en tiempo de ejecucin, razonamientos sobre su cdigo, etc. Es posible que quiera usar tcnicas distintas (o combinaciones de tcnicas) en las diferentes partes del programa. Justifique sus decisin en cada caso.

Explique qu tipo de errores espera encontrar (y cules no!) con su estrategia. Comente qu aspectos del diseo dificultaron o facilitaron la validacin.

2. Resultados del test (1/2 - 2 pginas).Resumen de qu pruebas se han realizadoy cules no, si es que queda alguna:qu mdulos se han probado, y si se han probado a fondo. Indique el grado de confianza del cdigo: Qu tipo de defectos se han eliminado? Cules son los que podran quedar?

4. Reflexin

La seccin de reflexin (vulgarmente conocida como "post mortem") del documento es donde puede hacer generalizaciones partiendo de xitos o fallos concretos, hasta llegar formular reglas que usted u otros puedan utilizar en el futuro desarrollo de software. Qu fue lo que ms le sorprendi? Qu hubiera deseado saber cuando comenz? Cmo podra haber evitado los problemas que encontr durante el desarrollo?

1. Evaluacin (1/2 - 1 pginas).Lo que usted considere xitos o fracasos del desarrollo: problemas de diseo no resueltos, problemas de funcionamiento, etc. Identifique cules son los rasgos importantes de su diseo. Seale tcnicas de diseo o implementacin de las que se sienta especialmente orgulloso. Explique cules fueron los errores que cometi en su diseo y los problemas que causaron.

2. Lecciones (0,2 - 1 pgina).Qu lecciones ha aprendido de la experiencia: cmo podra haberlo hecho de otra forma una segunda vez, y cmo los errores de diseo e implementacin pueden corregirse. Describa qu factores causaron problemas, como hitos errados, o errores y limitaciones conocidos.

3. Errores y limitaciones conocidos.De qu manera su implementacin no llega a alcanzar la especificacin? Sea exacto. Aunque perder puntos por errores y caractersticas no presentes, obtendr puntos parciales por identificar de manera exacta esos errores y el origen del problema.

5. Apndice

El apndice contiene detalles de bajo nivel acerca del sistema, que no son necesarios para comprenderlo en un nivel superior, pero que se exigen para usarlo en la prctica o para verificar afirmaciones realizadas en cualquier parte del documento.

1. Formatos.Una descripcin de todos los formatos adoptados o garantizados por el programa: para un fichero E/O (fichero para entrada y salida de datos), argumentos de la lnea de comando, dilogos de usuario, formatos de los mensajes para las comunicaciones en red, etc. stos deberan desglosarse en formatos visibles para el usuario, que son parte conceptual de los requisitos visibles para el usuario y del manual de usuario, y en formatos interioresque constituyen una parte conceptual de otros componentes de su documentacin.

2. Especificaciones del mdulo.Debera extraer las especificaciones de su cdigo y presentarlas por separado aqu. Si escribe sus comentarios en el estilo aceptado por Javadoc con eldoclet de 6.170, podr generar documentos de la especificacin de forma automtica a partir del cdigo. La especificacin de un tipo abstracto debera incluir su visin general, campos de la especificacin e invariantes abstractas (restricciones de especificacin). La funcin de abstraccin y el invariante de representacinnoforman parte de la especificacin de un tipo.

3. Casos de prueba.Idealmente, su banco de pruebaslee tests de un archivo de casos de prueba en un formato que resulta cmodo de leer y escribir. No es necesario que incluya casos de prueba muy extensos; por ejemplo, simplemente podra observar el tamao de una entrada aleatoria generada para realizar pruebas de estrs y proveer al programa que gener los tests. Indique cul es la utilidad de cada grupo de tests (ej. "pruebas de estrs, entradas enormes", "pruebas de particin, todas las combinaciones de +/-/0 para argumentos enteros").

Documentacin del cdigo

Comentarios a nivel de especificacin

Tipos de datos abstractos.Cada tipo de datos abstractos (clase o interfaz) debera tener:

1. Una seccin devisin generalque d una explicacin de una o dos lneas sobre qu objetos del tipo representan y si son mutables.

2. Una lista decampos de especificacin. Podra haber slo uno; por ejemplo, un conjunto podra tener el campoelemsrepresentando al conjunto de elementos. Cada campo debera tener un nombre, un tipo y una breve explicacin. Podra resultarle til definircampos derivadosadicionales que facilitaran la escritura de las especificaciones de los mtodos; para cada uno de stos, debera indicar que es derivado y explicar cmo se ha obtenido a partir de los otros campos. Puede que hayainvariantes de especificacinque restrinjan los posibles valores de los campos de la especificacin; si es as, debera precisarlos.

Especificaciones del mtodo.Todos los mtodos pblicos de las clases deberan tener especificaciones; los mtodos privados complicados tambin deberan especificarse. Las especificaciones del mtodo deberan seguir la estructurarequires(requiere), modifies(modifica), throws(lanza), effects(resulta),returns(devuelve) que aparece descrita en elboletn de especificacionesy en clase. Observe que para el curso 6.170, puede suponer que los argumentos no son nulos, de no especificarse lo contrario.

Comentarios a nivel de implementacin

Notas para la implementacin.Los comentarios de una clase deberan incluir los siguientes elementos (los cuales, en el caso de clases destacadas, aparecen tambin en la seccinEstructura en tiempo de ejecucinde la documentacin del diseo):

1. Unafuncin de abstraccinque defina cada campo de la especificacin en funcin de los campos de representacin. Las funciones de abstraccin solamente son necesarias para las clases que son tipos de datos abstractos, y no para clases de tipo excepciones o como cualquier objeto de la GUI.

2. Uninvariante de representacin. LasRIs(implementaciones de referencia) son necesarias para cualquier clase que posea una representacin (ej. no la mayora de las excepciones). Es muy recomendableque pruebe los invariantes en un mtodocheckRep()donde sea viable. Tenga cuidado al incluir en sus invariantes suposiciones acerca de lo que puede o no puede ser nulo.

3. Para las clases con representaciones complejas, aada una nota que explique laeleccin de la representacin(tambin conocida comorepresentacin racional): qu anlisis de ventajas y desventajas se realizaron y qu alternativas se han considerado y cules se han rechazado (y por qu).

Sentencias en tiempo de ejecucin.stas deberan utilizarse juiciosamente, como se explic en clase. Puede consultar Maguire Steve,Writing Solid Code,Microsoft Press, 1995, donde encontrar una discusin ms extensa sobre la forma en que las sentencias en tiempo de ejecucin pueden mejorar la calidad de su cdigo.

Comentarios.Debera comentar su cdigo cuidadosamente y con buen gusto. Las directrices estilsticas se encuentran disponibles en el boletn de laGua de estilo de Java Programa, calendario, material de clase, trabajos, exmenes, lecturas, otras fuentes, prcticas, presentaciones, herramientas y proyectos. Si desea obtener una excelente discusin sobre comentarios de estilo y est interesado en recibir muy buenos consejos sobre la programacin en general, consulte Kernighan Brian W. and Pike Rob,The Practice of Programming, Addison-Wesley, Inc., 1999.

Inicio