Cmo documentar un sistema de software

Objetivo
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 asuntos correctos. 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.
Otro asunto es cundo documentar. Aunque algunas veces es conveniente posponer la tarea de la
documentacin mientras se realizan experimentos, los programadores con experiencia suelen
documentar de forma metdica incluso el cdigo provisional, los anlisis de un problema inicial y los
borradores de un diseo. Ellos creen que esto hace que la experimentacin sea ms productiva. Adems,
dado que han tomado la documentacin como hbito, les resulta normal documentar a medida que van
avanzando.
Este boletn facilita directrices sobre cmo documentar un sistema de software como el proyecto 6.170.
Proporciona una estructura esquemtica y algunos elementos obligatorios, pero deja bajo su propio
criterio todo lo referente a los detalles. Es esencial que no piense que la documentacin es un asunto
rutinario y aburrido; si lo hace, su documentacin no servir para nada y ser penosa a la hora de leerla
y escribir. As que documente de forma consciente: pregntese a medida que lo hace, por qu lo hace y
si est empleando su tiempo de la forma ms eficaz.
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 programa diff de 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 objetivo del 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 problema proceden 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 los casos de uso le 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 como un 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 los invariantes 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. Su MDD (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 de suites de 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:blackbox y/o glassbox, top down (de arriba hacia abajo) y/o bottom up (de abajo hacia
arriba), tipos de test beds (bancos de prueba) y manejadores de tests que se han utilizado,
fuentes de datos del test, suites de 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 realizado y 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 interiores que
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 el doclet 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 representacin no forman parte de la especificacin de un tipo.
3. Casos de prueba. Idealmente, su banco de pruebas lee 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 de visin general que d una explicacin de una o dos lneas sobre qu objetos
del tipo representan y si son mutables.
2. Una lista de campos de especificacin. Podra haber slo uno; por ejemplo, un conjunto
podra tener el campo elems representando al conjunto de elementos. Cada campo debera
tener un nombre, un tipo y una breve explicacin. Podra resultarle til definir campos
derivados adicionales 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 haya invariantes de especificacin que 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 estructura requires (requiere), modifies (modifica), throws (lanza),
effects (resulta), returns (devuelve) que aparece descrita en el boletn de especificaciones y 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 seccin Estructura en
tiempo de ejecucin de la documentacin del diseo):
1. Una funcin de abstraccin que 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. Un invariante de representacin. Las RIs (implementaciones de referencia) son necesarias
para cualquier clase que posea una representacin (ej. no la mayora de las excepciones). Es
muy recomendable que pruebe los invariantes en un mtodo checkRep()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 la eleccin de la
representacin (tambin conocida como representacin 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 la Gua 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