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,