¿cual es la forma de documentar un sistema en Delphi?

[flystar]

Hola Hermanos.

Me encuentro realizando un sistema en Delphi.

Ustedes saben que a medida que se va desarrollando se va llenando de
código, algunos componentes visuales se van llenando de "acciones" cuando algo les sucede, unas cosas se van relacionando con otras y a veces pueden haber cosas "sutiles" que no se ven a simple vista pero suceden.

Me siento preocupado en como documentar de una manera correcta esta clase de sistemas...puede ser que en un futuro tenga que revisar el funcionamiento del mismo y si no tengo documentado nada, voy a tener que estar recordando y analizando componente por componente a ver cual tiene codigo programdo para cuando algo le sucede.
Además no todo se programa en código, algunos componente se configuran en tiempo de diseño y luego de tantos que hay, va a ser complicado recordar con que parametros se configuraron. Y eso hay que recordarlo y documentarlo.

No sé si Delphi 5 ya trae algo para hacer un reporte de "eventos programados para componente" y mas cosas al respecto de documentacion o que se yo..

Supongo que debe haber una forma adecuada y simple de elaborar una documentación completa, fácil de elaborar y de leer.

Soy un "cristiano" o "persona" normal, que solo busco la manera de documentar mi sistema de la manera facil y correcta. No pretendo nada tecnicamente complicado, solo deseo documentar para el futuro y consultas.

Alguna orientación ?

Gracias.

[rrf]

A nivel personal y con la misma preocupación que comentas tú, lo que hago es que incluyo muchos comentarios en el código:
// Esto se hace por tal cosa,
// los valores son: 1 para tal, 2 para cual, etc.

Y separo claramente (con líneas en blanco) lo que se hace en cada parte del código.

También, al inicio de una función o procedimiento, pongo un encabezado que deje claríto lo que se hace en él. Luego, dentro de esa sección o procedimiento, en cada parte voy aclarando lo que se hace.

Otro detalle es que utilizo nombres de variables y constantes que sean autoexplicativos. Por ejemplo: "Edicion_activada", "Se_inicio_busqueda", etc. Y lo mismo hago con los nombres de los procedimientos o funciones.

Al declarar variables o constantes, pongo a su lado un comentario que indique lo que hacen.

En general, por lo que he observado en el código que leo en el foro de otros miembros, todos seguimos reglas similares.

Lo que he notado en el código de otras personas es que dejan pocas líneas en blanco. Bueno, una cuestión de preferencias personales.

Hacer esto me lleva bastante tiempo y parece que no vale la pena, pero cuando llega el momento de localizar errores, hacer mejoras o modificaciones, lo comprendes todo muchísimo más rápido.

Espero te sirva.

Ramón.

[[Delphius]]

Hola flystar,
Yo en lo personal considero que una cosa es documentar algunas cosillas para aclarar el código y otra muy distinta es documentar apropiadamente el sistema, y el proyecto mismo sea de paso.

Por empezar, documentar a manera de comentarios es una práctica de doble filo. Por un lado nos aporta cierta claridad, pero en cuanto uno abusa de ello tenemos una mezcla de cosas y en vez de claridad tenemos obscuridad.
Hay que aprender que algunas cosas se pueden documentar dentro del código y otras afuera.

Algunos consejos:
1. Evitar comentarios superflúos. Nada de "aquí sumamos la venta al total". Lo obvio no va... sólo que lo realmente merezca la pena.
2. En lo posible evitar documentar dentro de implementation. Sobre todo si queremos añadir algunos comentarios respecto a una descripción general de algún procedimiento, función o método. Seguir ciertas buenas prácticas sugeridas por CodeGear es lo más sano. Documenta brevemente, en interface, en lo posible cualquier descripción general. Sobre todo algo como esto:


procedure HacerEsto....
{******************
Procedimiento: HacerEsto
Descripción: HacerEsto realiza bla ... bla...
Parámetros:
* Name: bla bla
Excepciones:
* EExceptionName: bla bla
*******************}
begin
....
end;

Es preferible que eso vaya a interface.

El asunto es no mezclar cosas y dejar al código lo más limpio posible.

3. Acostumbrate a formar tu estandar. Si trabajas en equipo, busquen entre todos una puesta en común y mantenganse firme en seguirlo. Respeten su formato. Nada de "Yo escribo a modo".

Ahora como dije al principio: hay cosas que es mejor tener afuera, en un documento aparte. Es muy tentador tener algo como eso en el código, ¿pero es tan necesario?
Depende. Muchas veces se necesita, y lo aconsejo, tener una descripción general sobre eso. Pero en vez de estar en las unidades es mejor tener un documento específico a ello.

Un documento en el que se tenga constancia de toda información que nos ayude. Una buena biblioteca a la que luego podamos consultar.

Se sabe que con el tiempo las cosas cambian. Y si no ponemos orden y control viene el caos. Es más que útil y necesario tener aceptado y formar un proceso medianamente formal de control de versión y cambios. Parte de la verdadera documentación es consumida por esto.

¿Qué se cambio?¿Cuándo? ¿Quien?¿Porqué?¿Qué efectos tuvo?¿En donde se produjeron cambios en cascada?

Por tanto es sano tener un buen uso de control de versiones. Es preferible algo como:

Nombre: HacerEsto [Proc]
Nro Versión: 3.2.13
Fecha: 28/04/2010
Autor: Marcelito alias "Mete pata"
Histórico:
* 3.2.12. Se añadió el parámetro Estado para bla bla

Descripcion:
bla bla bla

Y no he acabado... cuando se trata de documentar también se necesita llevar un documento sobre las pruebas. ¿O es que no querrás saber que se probó y que no?¿Los errores detectados y los que faltan por eliminar?

El asunto es que quiero asustarte. Porque si hay que documentar, se documenta en serio. Tómatelo en serio, de otro modo entonces no lo hagas, porque será para tí una actividad que te tomará tiempo de esfuerzo, y sobre todo de muchas ganas.
Hay que reconocerlo: ¡documentar es aburrido! El doctor NewDelphius te recomienda evitarse esto si es que no estás absolutamente convencido de que esto te será productivo y te aportará valor... el riesgo cardíaco aumenta con las grasas consumidas del día y del café incorporados tras 16 horas de picar código.... documentar después de todo eso es como comerse un lechón encima de un cabrito.

Y todavía no he acabado, he hablado de documentar código, de llevar un control de versión, de llevar un control de pruebas. ¿Vamos por más o esperamos a Halloween? ¡Vamos por más!

Otra parte de la documentación se la llevan los diagramas. Hay gente que los odia, otros que los aman. Son buenas herramientas, ayudan a aclarar muchas cosas. Lástima que cuando uno se enferma de diagramitis se da por enterado de que tiene encima 500 diagramas y sus glóbulos blancos no tienen conqué defenderse. Si te gustan los diagramas, hazlo. El doctor te recomienda en dosis moderadas. ¡No hagas más de la cuenta! ¡Es innecesario! ¡Limítate a los que te sean útil y te ayuden a aclarar ideas!

Tenemos: código, diagramas, control de versión de todo eso, planes de pruebas... ¡El paro está cerca!

¡Falta documentar sobre el proyecto! Que hicimos, que falta por hacer, ¿Cuánto hemos avanzado? ¿Estamos en lo planificado en lo que respecto: costos, tiempos, etc? ¿Los riesgos, como andamos?

Ufff.... Entonces, como salimos vivos: aprender a documentar sólo lo que nos sirva y cuando sea necesario.

Saludos,

[[maeyanes]]

Delphius, te faltó el manual de usuario...

[[Delphius]]

Empezado por maeyanes

Delphius, te faltó el manual de usuario...

Cierto, cierto... ¡Menuda cosa!
Ha... y por cierto, ya con esto infarto seguro... Hay dos tipos de manuales de usuario: el del usuario final y el manual técnico

Ha... ya sea de paso, digo... mejor vamos buscando el cajón porque todavía no se acaba. Luego de generar todita la documentación (proyecto + sistema + manuales) viene algo más chungo y más PRO... ¿quien adivina? ¿O es que se quieren evitar un infarto?

Luego viene documentación a nivel de empresa. Sacar conclusiones, generar ciertos informes que nos puede ser útil para saber como se hicieron las cosas. Mucha documentación que se lleva por cada proyecto puede ser empleada para generar otra más, que sea de utilidad para saber como encarar nuevos proyectos y reorganizar nuestro trabajo y redefinir nuestro propio método.
Por ejemplo: llegar a elaborar nuestro propio framerork, nuestras propias políticas de como llevar el dichoso control de versiones, etc.

En el caso del framerork es algo similar a la documentación para el sistema. Si analizamos los diferentes trabajos notamos que tener nuestras bibliotecas, nuestras clases, métodos, funciones y procedimientos nos puede ser de mucha ayuda a reducir nuestras actividades y además tiene el potencial de ser reutilizada. La pregunta aquí es ¿Y cómo sabemos si tenemos algo ya en nuestra biblioteca? Fáci... ¡documente mijo!

Y aquí el trabajo es doble, porque es natural que esta mega biblioteca o framework evolucione, cambie, se mejore... ¡Otra vez la burra al trigo con las versiones y las pruebas!

Para llegado el momento, si no tuvimos un infarto seguramente ya estemos por el doble Bypass. (y no me refiero a éstos ByPass).

Saludos,

[[AzidRain]]

Como ya te comentaron depende de que tipo de documentación vayas a realizar, la documentación del código la puedes hacer siguiendo los consejos que ya te dieron mas lo que a ti te acomode más. Es importante mantener un estilo constante al escribir código, por ejemplo si vas a usar:

 CamelCase, guion_bajo,  ESTILOBASIC, BASIC_CON_GUION

Si vasa usar variables de un solo caracter para índices (i,j,k...etc.)

La mejor práctica aunque la verdad muy tediosa y digna de asignar a una sola persona para hacerla, es escribir antes de cada función, procedimiento o clase una descripción detallada de que hace, que parámetros espera y que devuelve. Casí como una miniayuda de Delphi.

Y por supuesto utilizar algun control de versiones pues llegado el caso puede sucederte que algo que funcionaba deje de funcionar por algun efecto colateral, con este tipo de sistemas podrás regresar siempre a la versión que funcionaba o bien hacer "forks" para agregar o probar funcionalidades sin echar a perder lo que ya funciona y en caso de que todo salga bien unirlo nuevamente con lo que ya tenías.

Ya el caso de la documentación que se entrega con el proyecto es muy variable pues depende de lo que el cliente quiera, si lo vas a seguir atendiendo o bien lo va a mantener su propio staff y un sin fin de cosas.

Ya no te digo cuando es una aplicación comercial...ahi si...es un buen embrollo.

Por cierto, no sé si las últimas versiones de Delphi lo traigan pero que genialidad sería que existiera algo así como JavaDoc pero para Delphi, quienes ya lo hayan probado no me dejarán mentir que es lo máximo pues te crea prácticamente una ayuda en línea de tu propio sistema mientras lo vas desarrollando.

[[Delphius]]

Empezado por AzidRain

Por cierto, no sé si las últimas versiones de Delphi lo traigan pero que genialidad sería que existiera algo así como JavaDoc pero para Delphi, quienes ya lo hayan probado no me dejarán mentir que es lo máximo pues te crea prácticamente una ayuda en línea de tu propio sistema mientras lo vas desarrollando.

Desconozco si Delphi, en sus últimas versiones, tiene de fábrica para generar documentación, pero puedes contar con DelphiCodeToDoc.

Saludos,

[[AzidRain]]

Si lo conozco a DelphiCodeToDoc, pero no hace la belleza del Javadoc. En JavaDoc si documentas tu código de acuerdo con 3 o 4 simples reglas obtienes en automático "condeinsigth" con tu propio código, es decir, si pones el cursor del mouse sobre alguna función documentada te muestra lo que normalmente uno busca: parámetros, que devuelve y que hace) así como lo que ya hace delphi solo que con tu propio código, simplemente sensacional.

[Ñuño Martínez]

Llevo tres días diciéndome que tengo que subir a alguna parte el documento que tengo donde explica cómo documento mis programas en Pascal. Está en inglés, por diversas razones, pero sirve. Que alguien me lo recuerde a ver si esta tarde lo pongo en alguna parte.