INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

1 Introduccin El objetivo del presente documento es la especificacin de una serie de lineamientos que debern observarse para el desarrollo de los diferentes productos de software en el Departamento de Sistema y Computacin del INSTITUTO TECNOLOGICO de Morelia. Debe notarse, por una parte, que estas reglas constituyen un conjunto mnimo de los requisitos para la documentacin y organizacin de los productos de modo que el diseador/programador puede agregar ms documentos si lo considera necesario; por otra parte, estos lineamientos NO constituyen un reglamento estricto, sino un conjunto de normas flexibles que podrn ser cambiadas de acuerdo con las necesidades que vayan surgiendo. En este documento se entiende por un producto de software cualquier programa, paquete de rutinas, rutina aislada o sistema completo que involucre programacin (en cualquier lenguaje de programacin, inclusive de comandos). Un paquete es un conjunto de rutinas, funciones y/o macros que versan sobre algn tema particular; as pues, los elementos del paquete se relacionan entre s slo por el tema al que se abocan y aunque algunas rutinas hagan referencia o llamen a otras, todas ellas son elementos aislados que, en general, no requieren de las otras. Salvo por razones de prueba, un paquete no se concreta en un programa ejecutable sino solamente como un conjunto de mdulos objeto y/o fuentes que pueden estar agrupados en bibliotecas. Un sistema, a diferencia de un paquete, est constituido por un conjunto de elementos que interactan estrechamente, de tal manera que si alguno de ellos se elimina el sistema estar incompleto y por ende su funcionamiento ser inadecuado. Un sistema siempre se concretar en un programa ejecutable.

2 Documentos En los siguientes prrafos se describen brevemente los documentos mnimos que se requerirn para la presentacin de un producto de software. Entre parntesis, despus del ttulo de cada documento, aparece el nombre que ste deber tener, siempre que se sustituya el asterisco (*) por el nombre de su propio producto de software. En el encabezado de todos los documentos se deber indicar el nombre del archivo en que est el documento, as como su localizacin. En los documentos en que hubiere figuras, stas se deben mantener en archivo electrnico si estn digitalizadas, o bien en un flder de papel, pero en cualquier caso se debe indicar el mtodo para obtener esas figuras. 2.1 Lenguaje de los documentos Toda la documentacin debe elaborarse en espaol. 2.2 Documentacin de objetivos (*.dob) En este documento se debe describir el objetivo del producto. Esta descripcin consiste en la especificacin precisa del problema que el producto resuelve. El documento debe responder a la pregunta Para qu sirve este producto?

Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

2.3 Documento de requisitos (*.drq) En este documento se deben establecer los requisitos del producto, esto es, se deben definir claramente sus entradas y salidas as como los mecanismos para generarlas. En este documento de define tambin el comportamiento externo del sistema, de la rutina o del conjunto de rutinas del paquete, sin entrar al detalle de la forma o mtodo empleado para la solucin de los problemas. El documento debe responder a la pregunta qu debe hacer este producto? 2.4 Documento de anlisis y diseo (*.dad) Este documento debe contener todo el proceso de anlisis del problema; es decir los mtodos y tcnicas que se emplearon (o emplearn) para resolver el problema. Aqu se pueden incluir referencias a otros documentos o artculos relacionados con el problema y que pueden dar ms luz sobre el asunto. Este documento debe ofrecer una visin clara de cules son los problemas concretos que el producto deber resolver y de qu forma sern stos resueltos. Todos los productos requieren de un documento de diseo que permita identificar claramente cada una de las partes del producto y las interacciones entre ellas; ello puede implicar la presentacin de un diagrama conceptual del producto, en el que se viertan a manera de bloques y flechas los elementos y las interacciones. En el caso de sistemas modulares, se puede presentar un diagrama jerrquico de la estructura de esos sistemas. El documento debe responder a la pregunta Cmo lo hace? 2.6 Documentacin del cdigo El cdigo mismo del producto debe constituir un documento entendible. La documentacin de programas vara mucho dependiendo del estilo de redaccin de cada diseador. Esto no es tan importante dado que los diferentes estilos pueden llegar a ser igualmente eficaces. Dada la importancia de este punto en la seccin 4 se citan las pautas que deben ser respetadas. 2.7 Manual de generacin (*.dmg) Este es un manual en el que se darn todas las indicaciones pertinentes para generar el producto a partir de los archivos fuente. Se deben indicar aqu cules son los archivos fuente (con directorios inclusive), los mdulos objeto y bibliotecas que es necesario generar o, en caso de existir, el procedimiento de comandos que es necesario correr para la generacin automtica del paquete. 2.8 Manual de usuario (*.dmu) Para todo paquete o sistema se deber elaborar un manual de usuario en el que se indiquen los pasos necesarios para emplear el paquete o sistema. Segn el caso, debern observar las siguientes reglas: Paquetes. Se debe especificar con claridad: Parmetros. Nombre y tipo del parmetro. Uso del parmetro, esto es, si el parmetro se usa como entrada, como salida, o si tiene ambas funciones. Resultado de la funcin (tipo y significado del resultado), si tiene alguno y si no indicar que no tiene resultado alguno. Archivos de encabezado que es necesario incluir (directiva include) para poder emplear las rutinas. Mdulos o bibliotecas con las que es necesario ligar para poder emplear las rutinas.
2 Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

2. Sistemas. En este caso se debe especificar: Forma de activar el sistema. Descripcin de cada uno de los estados del sistema. Acciones para pasar de un estado a otro del sistema. Forma(s) para desactivar el sistema. El manual deber contar tambin con un buen nmero de ejemplos que ilustren adecuadamente el uso del producto. Para el caso de paquetes, parte de la documentacin incluida en este manual puede ser tomada de la documentacin que las mismas plantillas del cdigo obligan a incluir, pero debe notarse que no es la misma.

3 Organizacin del software 3.1 Directorios Cada producto se asignar a un miembro del proyecto que fungir como responsable del mismo y esta persona puede tener asignados varios productos; por consiguiente, se sugiere la siguiente organizacin para los archivos en directorios, para cualquier sistema operativo:

\Nom bre

Tem p

ProdA

ProdB

P rodC

D oc

C digo

R es

Directorio nombre. Este es su propio directorio personal, a partir de aqu se deben crear directorios para cada uno de los productos en desarrollo y adems un directorio temp. Directorio prodx. Es el directorio correspondiente a cada uno de los productos y debe llevar el nombre del producto que se est desarrollando. Este directorio contendr por lo menos dos subdirectorios, doc y cdigo, pero adems aqu se deben incluir los procedimientos de comandos que permiten instalar y/o generar el sistema o paquete a partir de los archivos fuente. Directorio doc. Este directorio debe contener toda la documentacin relacionada con el producto. Si la documentacin incluye figuras, estas podrn guardarse en forma digital en un archivo electrnico o podrn mantenerse en un archivo de papel aparte, pero aqu se deber indicar la forma en que se pueden recuperar u obtener esas figuras. Directorio cdigo. Este directorio est destinado a ser recipiente para todos los archivos fuentes del producto, objetos, bibliotecas y archivos de inclusin y si hay ejecutables, estos tambin debern estar en este directorio. En este directorio puede aparecer el directorio res. Directorio res. Este directorio se define slo para aplicaciones Windows o aquellas que necesitan la definicin de recursos de programacin (mens, cajas de dialogo, iconos, etc.)
3

Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Directorio temp. Este es un directorio en el que el propietario del rbol (nombre) desarrollar todos los trabajos que estn pendientes para su transferencia al rbol de directorios de otra persona, o aquellos que requieran de algn espacio temporal para su desarrollo.

3.2 Nombres de archivos Se recomienda que los archivos tengan las siguientes extensiones:
ARCHIVO DOS/Windows UNIX Fuente en C *.c *.c Fuente en C++ *.cpp *.cpp Fuente en ensamblador *.asm *.asm Objeto *.obj *.o Librera *.lib *.a Ejecutable *.exe * Tabla 3.1 Extensiones para los programas

En la tabla 3.1, el asterisco (*) representa el nombre genrico del archivo. 3.3 Diccionario Es necesario crear alguna utilera (o descubrir alguna existente), que permita localizar de manera gil todos los productos desarrollados o que estn desarrollando en un momento dado, dentro del proyecto.

4 Documentacin del cdigo 4.1 Convencin para los nombres (Notacin Hngara) La notacin hngara es una convencin de programacin para escribir cdigos fciles de leer. El concepto bsico es incluir el tipo de la variable en el nombre de ella. Esto permite que la lectura del cdigo sea ms rpida ya que para conocer el tipo de la variable no es necesario regresar a su declaracin. Especficamente, se coloca al inicio del nombre de la variable una abreviacin de mximo tres letras en minscula que indica el tipo de la variable (tabla 4.1).
Tipo de variable Abreviacin

Carcter con signo c Carcter sin signo b Entero n Entero sin signo (palabra) w Largo l Flotante f Doble d Cadena terminada en /0 sz Estructura Abc, donde Abc es el nombre sA de la estructura Objeto o Tabla 4.1 Abreviacin estndar en para el lenguaje C.

Enseguida del identificador de tipo en minscula, las variables se nombran usando una mezcla de maysculas y minsculas. Cada nombre de variable se selecciona de tal manera que indique su funcin. Se escribe su nombre con la letra inicial en mayscula seguida por el cuerpo en minscula. Para variables definidas por varias palabras, la letra inicial de cada palabra debe
4 Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

estar en mayscula (el nombre de una variable NO se escribe slo en maysculas). NO se deben usar guiones (_). Por ejemplo:
int long char struct Rect int char int int nTest; lTemp; *szString = "Prueba"; srRect; nMiVariableEjemplo; szEjemploString; NNOMBREINVALIDO; nNombre_Incorrecto

En general, use una variable para cada propsito, a menos que la variable sea para almacenamiento temporal sobre una seccin muy localizada en el cdigo. Para variables enteras que se usen como contadores de ciclo, las letras minsculas de la i a la m se usan solas. Para variables no enteras o para usos simples similares al conteo de ciclos, el tipo de la variable precede a la palabra Temp. Si se requieren ms de una variable temporal se deber usar un nmero progresivo al final (Temp1, Temp2, etc.). Por ejemplo:
int int long char i,j,k; nTemp; lTemp; cTemp1, cTemp2;

Los nombres de las funciones debern tener nombres descriptivos consistentes de una mezcla de maysculas y minsculas. Las funciones NO incluyen un indicador de tipo. Por ejemplo:
int int void char SampleFunction (void); AnotherSample (void); unMalNombre( ); OTROMALNOMBRE( );

Los nombres de las Clases debern ser descriptivos, iniciar con la letra C mayscula y consistir de una mezcla de maysculas y minsculas. Por ejemplo:
CNombre CMiClase Objeto_graf Cpincel // // // // nombre correcto nombre correcto Mal Nombre Mal Nombre

Las constantes simblicas (#define) debern escribirse todas en mayscula.

En los nombres de las constantes se pueden utilizar guiones entre palabras. Ejemplos:
#define #define #define BUENADEFINICION OTRA_BUENA_DEFINICION MalaDefinicion 100 120 300

Los grupos de definiciones relacionadas debern escribirse juntas, estar precedidas de un encabezado que defina su propsito y seguidas de un comentario que cierre el grupo.
Departamento de Sistemas y Computacin 5

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

// // lista de los colores vlidos en el sistema // #define ROJO 100 #define VERDE 200 ... #define AZUL 300 // Terminan las definiciones para colores

Las variables miembro de una clase y las variables que estn disponibles a todas las rutinas dentro de un mdulo, pero slo a un mdulo, debern estar precedidas de una m y un guin bajo. Por ejemplo:
int char char m_nVariableMiembro; m_szOtraVariable; szOtroNombre; //

mal nombre

4.2 Convenciones sobre comentarios 1.- Minimizar la necesidad de comentarios inmersos en el cdigo al usar: Prlogos estndar. Estructuras de control de programacin estructurada. Buen estilo al programar. Nombres descriptivos de acuerdo con la notacin hngara. 2.- Adjuntar comentarios al bloque de cdigo que: Realice manipulaciones de datos importantes. Simule construcciones de control estructuradas que manejen instrucciones goto Realice el manejo de excepciones. 3.- Usar la terminologa del dominio del problema y los comentarios. 4.- Emplear lneas en blanco, delimitadores, sangrado para realzar los comentarios y facilitar la lectura del cdigo. 5.- Colocar los comentarios a la extrema derecha para documentar cambios y revisiones. 6.- No manejan comentarios largos y confusos para aclarar un cdigo oscuro y complejo. Rescrbase el cdigo. 7.- Asegurar que el cdigo y los comentarios correspondan uno con el otro, as como los requisitos y especificaciones de diseo. 8.- No hacer comentarios que repitan lo que realiza el cdigo; por ejemplo: cont++; /* se aumenta el contador */ tampoco se deben hacen comentarios que sean jerga profesional: /* se sortea el archivo*/ 9.- Indicar el final de cada seccin importante cuando esto no sea obvio por otros indicios. 10.- El cdigo deber explicar cmo funciona el programa y la documentacin explicar por qu funciona y lo que hace. 11.- Siempre que se modifique un programa, deber modificarse la documentacin en los aspectos correspondientes.

Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

4.3 Prlogo para mdulo de sistema En esta seccin se aplica el trmino mdulo a cualquier archivo de cdigo que forma parte de un sistema. Todos los mdulos de un sistema debern tener al inicio el prlogo que aparece en la pgina siguiente (PROLOGO.TXT): El prlogo incluye: Mdulo: identificacin del mdulo dentro del sistema. Archivo: nombre del archivo con el cdigo fuente. Objetivo: descripcin de la funcin o el problema que resuelve el mdulo y una descripcin breve de cmo usarlo. Opcionalmente se puede mencionar las referencias y/o la bibliografa en las que se apoyo el diseador. Variantes. De acuerdo al tipo de archivo se deber llenar la variante propia. Dise: nombre completo del diseador del mdulo Implement: nombre completo del programador del mdulo Versin: fecha y/o nmero de la versin. Ultima actualizacin: este campo slo deber aparecer cuando el programa haya sido modificado por una persona diferente al autor. Por lo cual se debe anotar el nombre de la persona que modific el mdulo. El formato del prlogo para mdulo se puede grabar en un archivo PROLOGO.TXT e insertarlo en el archivo de trabajo cada vez que sea necesario.
/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo Archivo objetivo : : :

>> Variantes << (archivos *.h) Definicin de prototipos, variables simblicas, macros estructuras y tipos definidos para << aplicacin >> (archivos *.c) Cdigo y variables globales para << aplicacin>> (archivos *.hpp) Definicin de las clases: (archivos *.cpp) Implementacin de las funciones mtodo para la clase dise : Implement: Versin : Copyright: Copyright (c) 1996, ................. Todos los derechos reservados. --------------------------------------------------------------------*/ Formato del prlogo de programa

Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

A continuacin se muestra un ejemplo del prlogo para un cdigo en C.

/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo : Editor de texto Archivo : MIEDLIN.C objetivo : Cdigo y variables globales para el Programa de demostracin de las libreras para manejo de listas ligadas simples. El ejemplo consiste en un editor modal al estilo del "edlin" del sistema operativo DOS (v3.0). El programa se ejecuta tecleando el nombre del archivo a editar en la lnea de comandos: C:>MIEDLIN arch.ext Si el archivo ya existe se lee y se lista completamente, en caso contrario, se muestra un mensaje indicando que se trata de un archivo nuevo. El EDITOR tiene seis opciones: I ##: Insertar lneas a partir de la lnea ##, para salir del modo insertar se debe teclear control Z (<ctrl> Z) B ##: Borrar la lnea ## M ##: Modificar la lnea ## L : Listar el texto completo G : Grabar a disco el texto S : Salir del editor dise : Felipe Morales Lpez Implement: Felipe Morales Lpez Versin : enero/93 Copyright : Copyright (c) 1993, Felipe Morales Lpez Todos los derechos reservados. --------------------------------------------------------------------*/ Ejemplo del prlogo de archivo para el mdulo editor de texto.

4.4 Documentacin para Programacin Estructurada en C Un archivo de cabecera en C consiste de cinco elementos: El prlogo del archivo. Una directiva de preprocesamiento de compilacin condicional (#ifndef). Las funciones prototipo que necesita el archivo. Directivas de compilacin, includes, definiciones de tipos (typedef) propios del mdulo. La declaracin de compilacin condicional #endif. Ejemplo de un archivo de cabecera en C:
/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo Archivo objetivo : Listas genricas simples y dobles : DSLS.H : Definicin de prototipos, variables simblicas, macros estructuras y tipos definidos para Librera para construir y manejar listas ligadas, simples o dobles, de manera genrica

Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia dise : Morales Lpez Felipe Implement: Morales Lpez Felipe

Documentacin de software

Versin : Enero/93 Copyright: Copyright (c) 1993, Felipe Morales Lpez Todos los derechos reservados --------------------------------------------------------------------*/ #ifndef DSLS #define DSLS /*-------------------------------------------------------------------Variables simblicas --------------------------------------------------------------------*/ #define HEADDLS DlsPtr _next, _prev #define HEADSLS DlsPtr _next #define DSLS_D 2 #define DSLS_S 1 /*-------------------------------------------------------------------Definicin de tipos y variables externas --------------------------------------------------------------------*/ typedef struct _headdls *DlsPptr, DLHEAD, *HlsPtr, LSHEAD; typedef struct _headsls *LsPtr, SLHEAD; struct _headdls { DlsPtr _next; DlsPtr _prev; }; struct _headsls { LsPtr _next; }; /*-------------------------------------------------------------------Macros --------------------------------------------------------------------*/ #define BreakListDls(a,b,c) BreakListLs(a,(LsPtr)b,c, DSLS_D) #define BreakListSls(a,b,c) BreakListLs(a,b,c, DSLS_S) ... /*-------------------------------------------------------------------Prototipos de las funciones --------------------------------------------------------------------*/ extern void BreakListLs(HlsPtr, LsPtr, HlsPtr, int); extern DlsPtr CreateLs(HlsPtr); extern void* DeleteDls(HlsPtr, DlsPtr); extern void* DeleteSls(HlsPtr, LsPtr); extern void* DeleteLastDls(HlsPtr); extern void* DeleteLastSls(HlsPtr); extern void DestroyLs(HlsPtr *); extern void DestroyAllLs(HlsPtr *, void (*)()); ... extern void PushListSls(HlsPtr, HlsPtr); extern void SortInsertDls(HlsPtr, DlsPtr, int (*)()); extern void SortInsertSls(HlsPtr, LsPtr, int (*)()); #endif /*---------------fin del archivo -----------------------*/

Un archivo de cdigo fuente en C consiste de los siguientes tres elementos, (en ese orden): El prlogo del archivo. Los archivos de cabecera necesarios. Una descripcin de funcin y el cdigo declarativo para cada una de las funciones en el archivo.
Departamento de Sistemas y Computacin 9

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

El formato para la descripcin de una funcin es:

/*-------------------------------------------------------------------funcin : parmetros: objetivo: regresa : referencia: --------------------------------------------------------------------*/

Cada una de las secciones se detalla a continuacin: funcin: nombre que identifica la funcin, en algunos casos se puede agregar el programador, la fecha y el nmero de la ltima versin. parmetros: breve descripcin de los parmetros que recibe la funcin (nombre, tipo, contenido), indicando cuales de ellos se modifican. objetivo: declaracin del propsito de la funcin o subprograma y del mtodo aplicado. As como los cambios que produce. salida: breve descripcin del valor que regresa la funcin (tipo, contenido, significado). referencias: libro o artculo fuente cuando se desarrolla una funcin cuyo objetivo necesite una documentacin externa al programa. Otra forma de documentar una cabecera de funcin es la siguiente:
/*-------------------------------------------------------------------Funcin: NombreFuncin() Objetivo: Regresa: Referencia: Precondiciones: Postcondiciones: -----------------------------------------------------------------*/ Tipo NombreFuncin(VAR var1, // Descripcin de la variable var1 VAR var2, // Descripcin de la variable var2 etc. )

Donde NombreFuncin representa el nombre de la funcin. Las precondiciones y las postcondiciones representan las condiciones que se deben de cumplir antes de la ejecucin de la funcin y los cambios que provoca en el sistema la funcin. Se pueden omitir cuando no contienen informacin crtica. Por ejemplo:
/*-------------------------------------------------------------------funcin : DeleteDls (). objetivo: borra un "nodo" de una "lista" doblemente ligada. regresa : La direccin del nodo borrado de la lista o NULL si el nodo no se encuentra en la lista referencia: Estructura de datos (Tanembaun, 1990) --------------------------------------------------------------------*/ sdDslsPtr DeleteDsl( HlsPtr shLista, // cabecera de la lista DslsPtr sdnodo) // direccin del nodo que se desea borrar 10 Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Ejemplo que muestra el uso de un prlogo y el encabezado para funcin o subprobrama:

/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo : Listas Doblemente Ligadas Archivo : DLS.C objetivo: Cdigo y variables globales de la Librera para construir y manejar listas ligadas, simples y dobles, de forma genrica. dise : M.C. Felipe Morales Lpez Implement: Felipe Morales Lpez Versin : enero/93 Copyright: Copyright (c) 1993, Felipe Morales Lpez Todos los derechos reservados. --------------------------------------------------------------------*/ #include "DSLS.H" /*------------------------------------------------------------------funcin : BreakListLs parmtrs: sdLista = direccin de la cabecera de la lista a dividir slNodo = direccin del nodo de referencia. shList2 = direccin de la cabecera de la lista destino nTipo = tipo de la lista DSLS_S/DSLS_D objetivo: Divide la lista en dos, la nueva lista inicia en el nodo dado como referencia. regresa : Nada -------------------------------------------------------------------*/ void BreakListLs(HlsPtr sdLista, LsPtr slNodo,HlsPtr shList2,int nTipo) { ... } /*-------------------------------------------------------------------funcin : DeleteDls( ) parmtrs: shLista = cabecera de la lista. sdNodo = nodo que se desea borrar objetivo: borra un "nodo" de una "lista" doblemente ligada. regresa : Direccin del nodo borrado de la lista, NULL si el nodo no se encuentra en la lista referencia: Estructura de datos (Tanembaun, 1990) --------------------------------------------------------------------*/ void *DeleteDls(HlsPtr shLista, DlsPtr sdNodo) { DlsPtr sdTemp; if (FirstLs(shLista) == sdNodo) return((void *) PopDls(shLista)); if (LastLs(shLista) == sdNodo) return((void *)DeleteLastDls(shLista)); . . . NextDls(sdNodo) = NULL; PrevDls(sdNodo) = NULL; return ((void *)sdNodo); } Departamento de Sistemas y Computacin 11

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

4.4 Documentacin para Programacin Orientada a Objetos en C++ Un archivo de cabecera C++ consiste de seis elementos: El prlogo del archivo. Una directiva de preprocesamiento de compilacin condicional (#ifndef). Las funciones prototipo que necesita el archivo. Directivas de compilacin, includes, definiciones de tipos (typedef) nicos en el mdulo del sistema. Una descripcin de clase y el cdigo declarativo para cada una de las clases en el archivo. La declaracin de compilacin condicional #endif. Para la descripcin de la clase, se deber usar el formato siguiente.
/*--------------------------------------------------------------------Clase: Descripcin: Parmetros de creacin: Comportamiento del destructor: Operadores: Hereda de: Clases hijas: Notas: Dise: Implement: Versin: Copyright: Copyright (c) 1996, ................. Todos los derechos reservados. ---------------------------------------------------------------------*/

El significado de los elementos del formato es: Clase: Es el nombre de la clase y su descripcin Descripcin: Es una descripcin detallada de la clase y su comportamiento. Parmetros de creacin: Proporciona informacin acerca de cada uno de los constructores que se definen para la clase. Comportamiento del destructor: proporciona informacin acerca de lo que el objeto debe hacer cuando sea destruido. Operadores: lista los operadores sobrecargados para esta clase (+,-,=, operadores de conversin (cast) y otros). Hereda de: lista la clase o clases que estn directamente arriba de esta clase en la jerarqua de herencia. Clases hijas: lista la clase o clases que estn directamente abajo de esta clase en la jerarqua de herencia. Notas: notas varias acerca de los objetos (rango vlido, etc.) y notas acerca de la versin (quin dise, quin implement, nmero o fecha de la versin). Si las clases y sus operaciones las implementa el mismo programador, las notas de la versin se pueden escribir una sola vez en el prlogo del archivo.
12 Departamento de Sistemas y Computacin

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Este formato se puede grabar en un archivo llamado CLASS.TXT y leer como bloque en el editor de textos usado para escribir los programas. El siguiente listado es un ejemplo de un archivo de cabecera.
/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo Archivo objetivo : Archivos de entrada/salida : ARCHIVOS.HPP : Definicin de las clases clase CFile - archivos genricos. clase CRecordFile - archivo orientados a registros. clase CSecuencialFile - archivos secuenciales. clase CFileDlg - archivo para objetos de caja de dialogo. Dise: Felipe Morales Lpez Implement: Felipe Morales Lpez Versin: Enero/96 Copyright: Copyright (c) 1996, Felipe Morales Lpez Todos los derechos reservados. -----------------------------------------------------------------*/ #ifndef ARCHIVOS_H #define ARCHIVOS_H #include <windows.h> #include "StringIO.h" #include "programa.h" /*----------------------------------------------------------------Clase: CFile - archivos genricos Descripcin: Esta clase encapsula la conducta de un archivo genrico en C++. El archivo se abre automticamente cuando se crea un objeto de esta clase, y se cierra automticamente cuando el objeto se destruye. Parmetros de creacin: CFile( Str sFileName, int nMode = READ) sFileName = nombre del archivo (incluye trayectoria) a abrir. Se definen dos cadenas especiales: 1. "User Entered" pregunta al usuario el nombre del archivo durante el proceso de creacin. 2. "Temp File" abre un archivo con un nombre nico. nMode = modo de apertura del archivo READ o WRITE. Nota: si el archivo NO existe se crea. Comportamiento del destructor: Se cierra el archivo asociado. Para archivos temporales, el archivo adems se borra. Operadores: int() - convierte un objeto a manejador de archivo (int) de tal forma que se puede usar con cualquier funcin que necesite un manejador de archivo. Hereda de: Nadie. Clases hijas: CRecordFile - archivos orientados a registros CSequentialFile - Archivos secuenciales Notas: Ninguna -----------------------------------------------------------------*/ Departamento de Sistemas y Computacin 13

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Class CFile { protected: Str sFileName; // nombre usado durante la creacin BOOL bTempFile; // archivo temporal o NO int nFileHandle; // manejador de archivo para el archivo public: CFile(); CFile( Str sFileName, int nMode = READ); ~CFile(); Str GetFileName(void); void SetFileName(Str sNewFileName); operator int(); } ... #endif ARCHIVOS_H // conversin a manejador de archivos

Estructura para un archivo de cdigo fuente en C++ Un archivo de cdigo fuente consiste de los siguientes tres elementos, (en ese orden): El prlogo del archivo. Todos los archivos de cabecera necesarios. Una descripcin de funcin mtodo y el cdigo declarativo para cada uno de los mtodos en el archivo. Para la descripcin de una funcin miembro se deber usar el siguiente formato:
/*----------------------------------------------------------------Mtodo: Parmetros: Objetivo: Variables de clase usadas: Salida: Copyright: Cdigo original por: ................ Copyright (c) 2001, ................. Todos los derechos reservados. -----------------------------------------------------------------*/

De la misma manera que el formato para la declaracin de una clase, el formato de funcin miembro se puede grabar en un archivo con el nombre FUNCION.TXT. El significado de los elementos del formato es: Mtodo: es el nombre de la funcin mtodo. Parmetros: lista todos los parmetros, incluyendo los valores por omisin que son aplicables. Para parmetros que se utilizan para entrada de datos se deber incluir la palabra in entre parntesis. Para parmetros de salida (por ejemplo, un apuntador mediante el cual se escribe un resultado), se deber incluir la palabra out entre parntesis. Objetivo: contiene una breve descripcin de la operacin que realiza la funcin mtodo.
Departamento de Sistemas y Computacin

14

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Variables de clase usadas: lista las variables de clase que esta funcin mtodo lee o escribe directamente. Salida: describe el objeto que la funcin regresa (tipo, contenido, significado) Copyrigth: Notas sobre los derechos de autor. Si las clases y sus operaciones las implementa el mismo programador, las notas de la versin se pueden escribir una sola vez en el prlogo del archivo.

El listado siguiente muestra un ejemplo de un encabezado para cdigo *.CPP:

/*-------------------------------------------------------------------INSTITUTO TECNOLOGICO de Morelia Departamento de Sistemas y Computacin Mdulo : Archivos de entrada/salida Archivo : ARCHIVOS.CPP objetivo: Implementacin de las funciones mtodo para la clase Cfile, maneja archivos de entrada/salida CFile::CFile - constructor de la clase CFile CFile::Cfile - constructor alterno de la clase CFile CFile::~CFile - Destructor de la clase CFile::GetFileName - regresa el nombre del archivo en un string CFile::SetFileName - Actualiza el nombre del archivo CFile::operator int() - convierte a manejador de archivo dise : M.C. Felipe Morales Lpez Implement: Felipe Morales Lpez Versin : marzo/95 Copyright: Copyright (c) 1995, Felipe Morales Lpez Todos los derechos reservados. --------------------------------------------------------------------*/ #include <windows.h> #include <stdio.h> #include <io.h> #include "WinClass.h" #include "archivos.h" /*---------------------------------------------------------------------Mtodo: CFile::CFile constructor alterno de la clase CFile Parmetros: szName (in) - Nombre del archivo o "User Entered" para objetos que preguntan por el nombre al usuario, o "Temp File" para archivos temporales. nMode (in) - READ or WRITE Objetivo: mtodo que construye un objeto de la clase CFile. Si se tiene un nombre de archivo se abre en el modo indicado. Sino, en base a la clave se abre un archivo definido por el usuario del sistema o un archivo temporal. Si el archivo NO existe se crea. No se usa bloqueo de archivos ni otra proteccin multiusuario Variables de clase usadas: sFileName - Nombre usado durante la creacin. sTempName - Nombre temporal asignado por el sistema fh - Manejador de archivo para el archivo abierto. Salida: un objeto de la clase Cfile

Departamento de Sistemas y Computacin

15

INSTITUTO TECNOLOGICO de Morelia

Documentacin de software

Copyright: Cdigo original por: Felipe Morales Lpez Copyright (c) 1996, Felipe Morales Lpez Todos los derechos reservados. ----------------------------------------------------------------------*/ CFile::CFile (Str sNewFileName, int nMode) { sFileName = sNewFileName; bTempFile = FALSE; nFileHandle = INVALID; // Prueba para un archivo definido por el usuario if (sFileName == "User Entered") { ... } } ...

16

Departamento de Sistemas y Computacin