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.
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.
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.
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.
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.
¿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
B) Nuevo estilo Velneo vERP 2018
Yo voto por el del nuevo estilo. Los comentarios con guiones generan mucho «ruido» visual.
+ 1 al nuevo estilo para el 2018
Opción B
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é
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
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é
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…
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é
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,
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.
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)
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.
El nuevo estilo Velneo vERP 2018 es mas limpio, +1
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).
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.
Me parece más limpio y fácil de leer el nuevo estilo (2018). Estéticamente… para gustos colores.