Lógica mente

El blog de Jesús Arboleya

  • Inicio
  • Buenas prácticas
  • Vitaminas
  • Podcast
  • Blog
  • Contacto

El comando REM, sin comentarios

Comentarios nuevo estilo 2017

No hay nada peor que un código sin ninguna línea de comentarios

Aunque el ejemplo de la imagen que se muestra a continuación es muy sencillo, ver un código sin ninguna línea de comentario resulta extraño, al menos un mínimo comentario general siempre ayuda a saber cuál es el objetivo de ese código cuando sea ejecutado. Con ese mínimo esfuerzo evitamos tener que leer bastantes líneas del código para intentar comprender cuál es su objetivo. En un proceso normal con decenas de líneas de código los comentarios se convierten en algo imprescindible para conseguir la calidad y mantenibilidad que todo buen código requiere.

Sin comentarios

Si las comentas no se ejecutan

En el código Velneo el editor permite «comentar» líneas para evitar borrarlas y poder descomentarlas para que vuelvan a estar activas y se ejecuten. Se puede comentar con el 4º botón de la toolbar del editor de código o con la tecla aceleradora Shift+F6. Las líneas de comentarios que usan el comando REM se ven, por defecto en negrita, sin embargo si las comentamos conseguimos que no se destaquen en color verde.

Comentarios Estilo vERP 2016

No dejes libres por el medio sin comentar

Cuando veo código en consultorías o soportes es habitual ver programadores que dejan líneas libres por el medio o al final del proceso, función, manejador o trigger. Estas líneas también se evalúan aunque sea para saber qué no hay nada que ejecutar. Por lo tanto además del efecto visual de falta de rigor es recomendable no dejar líneas libres en ningún lugar del código, salvo cuando lo hacemos voluntariamente para añadir espacio entre líneas. Muchas veces estas líneas son el resultado de crear unas cuantas líneas con la intención de abrir un bloque de código a escribir y posteriormente se nos olvida quitarlas, por ese motivo es más recomendable no crearlas e ir añadiendo (Ctrl+Intro) o insertando (Shift+Intro) líneas según vaya siendo necesario. Otra forma muy habitual de añadir líneas es copiar/pegar otra línea o líneas.

Líneas libres

Comenta lo justo y necesario

Los comentarios son unas parte importante de nuestro código que facilita su comprensión y mantenibilidad. Por ese motivo se recomienda hacer un buen uso de los comentarios:

  • No dejes sin comentar nada importante.
  • No pongas comentarios si no aportan información relevante, no comentes obviedades del código.
  • Comenta pensando en otros programadores o en ti mismo para dentro de unos años.
  • Comenta para generar bloques de código que facilite su lectura.

Comentarios nuevo estilo 2017

Bloques de código vs comentarios locales

En la siguiente imagen podemos ver un ejemplo con 2 tipos de comentarios. Los de bloque que son aquellos que tienen una línea libre encima y otra debajo de la línea REM y que ayudan a crear «bloques» de código más fáciles de leer por el programador. Y por otro lado están las líneas REM locales que van solas y que ayudan a documentar aspectos muy concretos de la línea o líneas siguientes sin tener el ámbito de comentario general de un bloque completo de líneas.

Bloques de comentarios vs comentarios locales

¿Qué opinas?

Para finalizar me gustaría conocer tu opinión. A continuación te voy a repetir 2 capturas utilizadas anteriormente en este artículo. La primera corresponde al estilo empleado durante 20 años y que todavía seguimos usando en el código de Velneo vERP. La segunda es un nuevo estilo más simplificado que estamos probando para ver si lo aplicaremos en Velneo vERP a partir de 2018. Te agradecería que me dejes un comentario con tu opinión sobre cuál consideras que cumple mejor la función de documentar bloques de código y por qué, ten en cuenta que la pregunta no es ¿Cuál te gusta más? No se trata de hacer una valoración estética sino cuál te ayuda a leer mejor y con menor esfuerzo cognitivo los bloques de código. Muchas gracias por tu colaboración.

A) Estilo Velneo vERP 2017

Comentarios Estilo vERP 2016

B) Nuevo estilo Velneo vERP 2018

Comentarios nuevo estilo 2017

Archivado en: Buenas prácticas


Escrito por Jesús Arboleya.
Evangelista y consultor de Velneo en el departamento de éxito de clientes.

Comentarios

  1. Rafa dice

    05/09/2017 en 08:59

    Yo voto por el del nuevo estilo. Los comentarios con guiones generan mucho «ruido» visual.

    Responder
  2. Francisco José Vila Martín dice

    05/09/2017 en 09:33

    + 1 al nuevo estilo para el 2018

    Responder
  3. Mario Conde Fornós dice

    05/09/2017 en 10:25

    Opción B

    Responder
  4. Paco Satué dice

    05/09/2017 en 12:26

    Hola Jesús.

    Realmente las dos soluciones son visualmente equivalentes, ya que lo que realmente resulta decisivo es el uso del color verde al que el ojo humano es más sensible e interpreta esas líneas como un bloque compacto.

    Puestos a elegir, por supuesto la segunda opción, porque chirría mucho menos. No tiene sentido usar la ristra de guiones en un entorno visual y asistido como Velneo.

    De todas formas, ¿no sería más life-is-soft que el editor insertara directamente las líneas Rem y Libre comentadas ya que siempre es lo más óptimo para el intérprete?

    Otra solución, mucho más óptima, es que los proyectos encriptados que se descargan en el cliente (o ejecuta el vServer) estuvieran limpios de cualquier línea Rem, Libre o comentada. Incluso se optimizaría la descarga inicial al reducir de manera apreciable el tamaño de los proyectos.

    Saludos
    Paco Satué

    Responder
    • jarboleya dice

      05/09/2017 en 12:35

      Buenos días Paco.

      Gracias por tu comentario.

      Respecto a los colores hay que tener en cuenta que no todo los ojos son iguales, te lo digo empezando por los míos, es cierto que este verde en concreto resalta notablemente respecto al negro, pero en otras tonalidades a los que somos daltónicos nos resulta más compleja la diferenciación. Yo creo que además del color el espacio en blanco es el otro gran aliado para generar el concepto de bloque. En mis pruebas si no pongo los libre aunque la REM en verde se lee bien diferenciar los bloques de código requiere una mayor carga cognitiva.

      Que el editor comentase la línea REM si le veo sentido, sin embargo al libre no, porque sino cada vez que añadimos una línea nueva tendríamos que descomentarla.

      Hablo de memoria pero creo que las líneas comentadas no se incluyen en los proyectos que envía el vServer. Lo que no tengo claro es si las REM se incluyen o no. Intentaré asegurarme y actualizo el artículo si hay alguna información relevante.

      Un cordial saludo.
      Jesús

      Responder
      • Paco Satué dice

        05/09/2017 en 17:16

        Hola Jesús.

        Tú tienes problemas de daltonismo y yo de agudeza visual (presbicia). Está claro que necesitamos un editor de código en el que podamos personalizar los colores de los comandos y establecer el tamaño de texto más adecuado a nuestro confort de trabajo.

        En cuanto a comentar las líneas Libre no había caido en ese detalle. Aunque tiene fácil solución si se habilita en la toolbar un nuevo botón que ejecute una macro para insertar las 3 líneas comentadas del bloque.

        Saludos
        Paco Satué

        Responder
        • jarboleya dice

          05/09/2017 en 19:41

          Jejejeje, me da rabia responder que yo tengo presbicia también, pero que se le va a hacer, la edad es la edad, yo la verdad es que del tamaño de letra no tengo quejas, que todo sea configurable sería lo ideal, pero tengo que reconocer que tanto colores como tamaño para mi es válido, supongo que para los jóvenes será demasiado grande 🙂

          Respecto a de comentar líneas, yo creo que más que un botón que haga eso puestos a pedir para Reyes me gustaría tener un gestor snippets de código Velneo. Pero como me suelo portal mal…

          Responder
          • Paco Satué dice

            05/09/2017 en 22:19

            Bueno, bueno, … intentaremos portarnos bien.

            Seguro que el jóven equipo de desarrollo de Velneo comprenderá nuestras limitaciones físicas, que el tiempo pasa inexorablemente para todo el mundo.

            Saludos
            Paco Satué

  5. Antonio Vela dice

    05/09/2017 en 20:08

    Hola chic@s,

    Como alternativa para la versión de Velneo vERP 2018 me quedo con la opción B.

    Pero creo que cuanto más documentemos los procesos será mejor para todos los desarrolladores.

    Me inclino en que sea el vInstallbuilder el que se encargue de eliminar antes de generar el .VIN el que elimine todas las líneas y líneas REM que no se tengan que intrepretar a la hora de la ejecución.

    Un saludo,

    Responder
    • jarboleya dice

      05/09/2017 en 22:15

      Hola Antonio,

      Gracias por tu comentario.

      Está claro que la opción está ganando por goleada 🙂

      Respecto al tema de eliminar las líneas libre y REM al generar el vInstallBuilder no lo veo, fundamentalmente porque el creador de instalaciones no solo se usa para llevar proyectos a servidores de producción, sino que también se utiliza para mover proyectos entre servidores de desarrollo. En cualquier caso si al generar el .vin se eliminasen esas líneas de los proyectos y una instalado editaremos esos proyectos con vDevelop habríamos perdido todos los comentarios, por eso no lo veo como una opción válida. Por eso creo que es mucho mejor que sea el vServer el que los quite cuando los sirve al vClient, porque el código fuente permanece intacto, y como le comenté a Paco, creo que es así, al menos con las líneas comentadas y no estoy seguro de las REM no comentadas ni de las libres.

      Un cordial saludo.

      Responder
  6. Fernando Maltrana dice

    06/09/2017 en 15:34

    Me gusta una combinación de ambas

    Cuando un mismo proceso (largo) internamente tiene varios bloques diferenciados me parece más claro separarlos con rayas, los comentarios de los pasos dentro de esos procesos con líneas libres… si ves el proceso no deberías tener muchos comentarios con rayas…. si tienes muchos hay que refactorizar. (por que en realidad lo que hay que evitar es esos procesos largísimos)

    Responder
    • jarboleya dice

      06/09/2017 en 15:51

      Hola Fernando.

      Muchas gracias por tu aportación.

      Tienes razón en que hay momentos en que se necesita «romper bloques», pero no es menos cierto lo que comentas que eso es sinónimo de que el proceso tiene más de una responsabilidad. Así que gracias porque me has dado la idea para un nuevo post que voy a escribir precisamente sobre la buena práctica de conseguir que un proceso tenga una única responsabilidad aunque no sea fácil de conseguir en el día a día, pero para eso está como bien indicas la refactorización, el mayor problema es que las cosas que no haces bien en el momento de su creación suelen quedar así para siempre.

      Voy a escribir otro post con las conclusiones de éste indicando un procedimiento de cómo vamos a comentar en vERP ya que al final hay unos cuantos matices a tener en cuenta en función de la posición del comentario.

      Un cordial saludo.
      Jesús.

      Responder
  7. Luis Palomo dice

    06/09/2017 en 16:19

    El nuevo estilo Velneo vERP 2018 es mas limpio, +1

    Responder
  8. Ramon Denuc dice

    08/09/2017 en 12:30

    Yo la verdad utilizo las dos opciones, por el simple hecho de que a veces necesito romper bloques de código largos, y combinó la opción 2017 (Guiones) con la opciones 2018.

    Pero de todos modos si hay que votar me tiro por la opción 2018.

    También me gustaría secundar la sol·licitud casi històrica de Paco Saute, de que lo ideal sería poder configurar a nuestras necesidades el editor, tamaño, colores, etc.

    Esencialmente porque yo también tengo problemas visuales, y a los jóvenes, recordaros que un día llegaréis a ser algo más mayores, ja, ja. (todo llega).

    Responder
    • jarboleya dice

      12/09/2017 en 22:18

      Gracias por tu aportación Ramón.

      Aprovecho para comentar que he confirmado que actualmente la versión que recibe el vClient del servidor para su ejecución recibe los proyectos comprimidos e integros. Es decir, que el código fuente de nuestros procesos que se ejecuta es el mismo que nosotros dejamos programado en el editor de vDevelop. Por lo tanto todo lo dicho en el post sigue teniendo el mismo sentido y debemos mimar como siempre nuestro código, al fin y al cabo son los hijos digitales de los programadores 🙂

      Un cordial saludo.
      Jesús.

      Responder
  9. Darío Buhigas dice

    16/12/2018 en 12:37

    Me parece más limpio y fácil de leer el nuevo estilo (2018). Estéticamente… para gustos colores.

    Responder

Trackbacks

  1. Nuevo estilo de comentarios en Velneo vERP dice:
    12/09/2017 a las 23:13

    […] raíz del feedback recibido en “El comando REM consume tiempo, sin comentarios” hemos trabajado en el que será desde ahora el nuevo estilo de comentarios que usaremos en Velneo […]

    Responder
  2. Nuevo estilo de comentarios en Velneo vERP | Velneo dice:
    28/09/2017 a las 09:57

    […] raíz del feedback recibido en “El comando REM consume tiempo, sin comentarios” hemos trabajado en el que será desde ahora el nuevo estilo de comentarios que usaremos en Velneo […]

    Responder
  3. ¿Cómo comentar bien el código de una aplicación hecha en Velneo? | Velneo dice:
    28/09/2017 a las 10:25

    […] raíz del feedback recibido en “El comando REM consume tiempo, sin comentarios” hemos trabajado en el que será desde ahora el nuevo estilo de comentarios que usaremos en Velneo […]

    Responder

Deja una respuesta Cancelar la respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.

Copyright © Jesús Arboleya 2022