Continuamos 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.
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:
Aquí 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:
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:
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:
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)
