BLOG

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

Por [N4] fgutierrez.velneo el | 8 Comments

Finalizamos esta serie de artículos sobre la documentación de aplicaciones tratando el uso del comando de instrucción Rem en procesos.

Como los procesos en Velneo V7 son asistidos, el código ya de por si se autoexplica, pero siempre es interesante añadir información que permita entender rápidamente cómo funciona más adelante, cuando volvamos al código pasado un tiempo, o para otros programadores que lean nuestro código,

Sobre cómo documentar procesos encontraremos siempre mucha información, muchos métodos, ya que siempre ha sido un tema muy tratado por los programadores. En la web, encontraremos muchas ideas y formas de documentar, formatos distintos según el lenguaje,  uso de etiquetas y procedimientos, etc., pero muchas ideas comunes.

Aprovecharemos a ver algunas formas de comentar con Velneo V7.

Normalmente, documentaremos en nuestro código los algoritmos que usamos, explicaciones de los parámetros usados en procesos y funciones y sus valores posibles, etc.

Los comentarios, además, nos permiten agrupar las líneas de código, para delimitar bloques y de esta manera destacarlos.

Esta forma de delimitar el código solemos usarla, sobre todo, cuando el código es largo, para hacer ver los distintos pasos que se van dando en el código.

Pero también separamos conjuntos de líneas cuando tienen una cierta importancia: una implementación complicada, un truco, algo que haya que cambiar u optimizar, etc.

Incluso podemos indicar que no está bien programado y que ha de volver a hacerse.

El uso del comando Rem nos permite todos estos usos, mostrando la información contenida en este comando en negrita, de tal forma que destaque en el código.

Además, tenemos la opción de “Comentar” una línea de código Desactivando una línea. De esta forma, la línea permanece en el código pero no es ejecutada. Esto puede ser útil cuando probamos distintas opciones.

E incluso el uso de una línea Libre puede ayudarnos a aclarar un poco más un proceso.

Estilos

Con estilo nos referimos al formato, a la forma en que se maquetan los comentarios, cómo debemos escribirlos y decorarlos.

Hay quien prefiere una línea simple de comentario, o deja un espacio antes del comentario para que se destaque aún más, o introduce líneas u otras decoraciones en el comentario cuando separa bloques, etc.

Lo más importante es que sean coherentes, es decir, que en todos los puntos del código nos encontremos que está documentado de la misma forma.

Pero también el estilo define dónde y cómo documentar. Por ejemplo, si decidimos que las variables han de explicarse al principio del código, entonces hemos de hacerlo así en todos los procesos, y no encontrarnos que unas veces se documenta en el propio proceso y otras veces hemos de ir al subobjeto variable a revisar su funcionamiento.

Etiquetas

Dentro del estilo, está también el uso de etiquetas. Existen una serie de etiquetas que vienen del inglés y que son más o menos estándar, de las que también, por supuesto, podemos hacer uso en su versión en castellano. Un ejemplo:

  • TODO:// Descripción de lo pendiente
  • NOTE:// Descripción de la nota
  • FIXME:// Descripción del código que se ha de revisar, optimizar o rehacer porque es incorrecto

Luego, cómo usemos los comentarios para documentar es cosa nuestra: debemos tener cuidado en no expresar cosas evidentes, sobrecargar de comentarios, tener en cuenta que ese texto lo pueden leer otras personas, ser coherentes, tampoco perder mucho tiempo en contar más de la cuenta, actualizar los comentarios a medida que programamos, etc.

La organización como elemento de la documentación

La organización de un proyecto es muy importante, tanto como la documentación o más. Una normalización coherente ayuda a entender cómo está programado, tanto a nivel organizativo de objetos, uso de identificadores, nomenclatura, etc.

Por eso hemos realizado Propuesta de normalización, que tiene la intención de facilitaros una serie de reglas que permitan hacer más accesibles vuestras Velneo Open Apps a otros programadores, de tal forma que conocer e integrar éstas sea más sencillo.

Y tú, ¿cómo lo haces?

¿Dónde documentas y cómo? ¿Que estilo usas? ¿Qué etiquetas usas? ¿Qué recomendaciones tienes para los programadores de Velneo V7?

Velneo es el entorno ágil para el desarrollo
de aplicaciones empresariales

DESCARGAR VELNEO

8 Responses to "¿Cómo documentas tus proyectos?: Rem en procesos (y III)"
  1. Lo que no estaría de más para poder documentarlos es poder imprimir los procesos
    un saludo
    Miguel

  2. [N1] glpunzi.lordzealon dice:

    Y no sólo imprimir, si no por ejemplo, en otros lenguajes, si pones en un comentario la etiqueta TODO, luego, desde un panel, puedes ver todos los TODOs que hay, y al hacer doble click, te llevaría al TODO en cuestión. Esto es super útil para ir quitando tareas pendientes de en medio, sin tener que volverte loco buscando.

  3. [N1] agustinsmv.gmail dice:

    Yo, respondiendo a la pregunta del artículo, lo documento a mano, con papel amarillo y escrito con pluma estilográfica.
     

  4. [N3] gegeo dice:

    Yo sigo a fecha de hoy, con cuaderno de anillas, hoja cuadriculada y lapiz.
    Algun pantallazo que imprimo y lo grapo a la hoja cuadriculada que le corresponde.

  5. Pues mirado desde ese punto  de vista, en realidad no pudiendo imprimir nos hacen un favor, asi se conservan las tradiciones, no habia pensado en esa posibilidad, pues nada agradedido…
    Miguel

  6. [N2] Comercial.arhes2000 dice:

    Manda guevos, como dijo uno… 🙂 🙂 🙂
     
     
    Saludetes.
    Miguel.

  7. [N1] agustinsmv.gmail dice:

    Y mandó dos docenas, mgalvez, y mandó dos docenas 🙂 🙂
     
    Un saludo

  8. [N1] agustinsmv.gmail dice:

    Eso me recuerda un viejo chiste, para darle algo de alegría al foro:
    Un hombre entra en la panadería y le dice al dependiente
    – Deme dos barras de pan, y si tiene huevos, dos docenas.
    Y el hombre se fue con 26 barras de pan para casa  .-)

Deja un comentario

Esta web utiliza cookies. Si continúa navegando acepta dichas cookies y nuestra política de cookies. Gracias. ACEPTAR

Aviso de cookies