Blog

¿Cómo documentas tus proyectos?: Propiedad Comentario (II)

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 1Continuamos esta serie de artículos sobre la documentación de aplicaciones con éste en el que tratamos la propiedad Comentario de los objetos.

Esta propiedad está presente en todos los objetos, y a fuerza aparecer en todos ellos, puede hacer que llegue a pasarnos desapercibida. Al igual que el identificador del objeto, el nombre y los estilos, la propiedad Comentario es compartida por todos ellos; y la razón es, claramente, que la documentación de nuestros proyectos es muy importante.

Que encontremos esta propiedad en todos los objetos puede hacernos pensar que puede hacerse muy pesado rellenar información en los Comentarios para cada uno. Si tenemos paciencia podemos hacerlo, pero sí que hay sitios donde puede ser casi imprescindible hacerlo.

En los objetos, con el identificador y el nombre suele ya darse la mayor parte de la información necesaria para entender para qué sirve o donde se usa. Aún así, podemos añadir información relevante y, sobre todo, advertencias de su uso o reutilización.

Por ejemplo, podemos indicar cuáles son los formularios o rejillas por defecto para la explotación de una tabla, indicando por otro lado aquellos formularios o rejillas especiales para ciertos usos.

Donde hay más cancha para su uso, va a ser en los subobjetos, y ahí veremos varios ejemplos:

Por ejemplo, en campos de una tabla:

Hay veces que debemos tener en cuenta los valores posibles de un campo, condiciones concretas, dónde se debe usar y dónde no, explicar los enlaces especiales que se establecen, etc.

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 2

Aunque la resolución del índice nos lo indica, no está mal aclarar a qué registro apunta un singular de plural.

Por ejemplo, en los componentes de una actualización:

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 3Aquí el detalle está en explicar cuál es el estado 3, que de otra forma deberíamos buscar en el proyecto de datos.

Por ejemplo, en los componentes de una búsqueda:

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 4

De nuevo, los comentarios nos permiten aclarar qué significa un literal que, de otra forma, nos obligaría a buscar su significado para entender esta búsqueda.

Por ejemplo, en variables locales de proceso:

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 5

Muchas veces es interesante especificar aún más qué es lo que guardamos en una variable.

Por ejemplo, en variables que son parámetros de funciones de proceso:

¿Cómo documentas tus proyectos?: Propiedad Comentario (II) 6

Y todavía más interesante conocer qué debemos pasar como parámetro a una función de proceso.

Estos son sólo unos ejemplos de su uso en nuestros proyectos. Seguro que se te ocurren muchos más sitios donde puede ser interesante añadir algo de información en forma de comentarios.

Continuará en: ¿Cómo documentas tus proyectos?: Rem en procesos (y III)

6 thoughts on “¿Cómo documentas tus proyectos?: Propiedad Comentario (II)

  1. Todo esto esta muy bien pero seria interesante que el vDevelop fuera capaz de generar un documento con todos estos datos bien estructurados, de esa forma tendríamos un documento como base para realiza una documentación de todo el proyecto.
     
    Saludos
     

Dejar un comentario