Aprovechando el post de Jesús Arboleya sobre el trabajo que estamos haciendo en relación con los comentarios del código de la nueva versión Velneo vERP, queremos mostraros la forma en la que uno de los mejores programadores de la plataforma está pensando en comentar el código, en este caso el código de Velneo vERP. Este tema está abierto a opiniones y si queréis podéis dar vuestro parecer en la sección de comentarios.A partir de aquí mostramos íntegramente el artículo de Jesús Arboleya de cómo está pensando en comentar la siguiente versión de Velneo vERP:A 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 vERP a partir de la versión 22.
Los objetivos
El primer objetivo es que los programadores que vean el código lo puedan leer y entender con la menor carga cognitiva posible.El segundo es que el sistema de comentarios sea sencillo de comprender y aplicar, y por lo tanto los desarrolladores lo apliquen de forma rápida, sencilla y homogénea.
Criterios base con matices
Los criterios base a aplicar son los siguientes:
- Los comentarios se escriben con líneas aplicando el comando REM.
- Las líneas de comentarios se “comentarán” para que queden de color verde destacando del resto del código y evitando su evaluación en ninguna circunstancia.
- Si el texto del comentario es muy largo y no se ve por completo en pantalla se dividirá en varias líneas REM.
- Las separaciones de código o comentarios se conseguirán empleando líneas libre antes de la línea de comentario REM.
- Las líneas libres también se “comentarán” para facilitar su lectura y creación del concepto de bloque
Sobre estos criterios base debemos tener en cuenta diferentes excepciones o matices a la hora de aplicarlos en función de la localización.A continuación se muestra la lista con los diferentes tipo de líneas de comentarios que espero te resulten lógicos y fácil es de aplicar si deseas usarlos en tu código.
Comentario de inicio de código
Es conveniente que el código comience con una descripción general del mismo. En muchos casos puede coincidir con la descripción del objeto: proceso, función, manejador de evento, etc.Esta línea REM no requiere ninguna línea libre anterior ni posterior.
Comentario de log de cambios
Si el cambio de un código requiere ser documentado y declarado de forma explícita se añadirá tras el comentario descriptivo de inicio de código una o varias líneas de log. Estas líneas estarán separadas de la descripción inicial por una línea libre.El formato de la línea de log será:
Aunque en Velneo vERP no es necesario indicar el nombre o nick del programador, si se considera importante para el desarrollo en equipo se aplicará el siguiente formato:
Comentario antes del código y después de la descripción
Si una vez añadida la línea REM de la descripción general es necesario poner un comentario antes de la primera línea de código se separarán ambas líneas de comentarios por una libre.
Comentario inicial de un nuevo bloque en el mismo nivel
Para conseguir que ambos bloques de código queden claramente separados visualmente se aplicará una línea libre antes del comentario consiguiendo que el espacio en blanco ayude a separar ambos bloques.
Comentario en primera línea de un bloque sangrado
Cuando hay bloques de código que se escriben con sangrado debido a comandos de intrucción que generan subprocesos como ocurre con los comandos if, cargar lista, recorrer lista, etc. No será necesario poner una línea libre ya que el sangrado consigue el efecto de separación de bloques y una línea libre genera demasiada separación.En el caso de los comando if, else y elseif las líneas de sus subprocesos si empiezan con un comentario lo harán siempre sin necesidad de incluir anteriormente una línea libre.
Comentario en primera línea tras finalizar un sangrado
Aunque la finalización de un sangrado ya genera separación visual del código, la primera línea tras recuperar el nivel de código anterior conviene que si comienza con comentario tenga una línea libre anterior ya que nos ayudará a comprender que existe código anterior al mismo nivel.
Comentario local a un línea dentro de un bloque
Cuando un comentario se utilice para documentar la línea o línea siguientes, pero no a todas las líneas del bloque, este comentario no incluira una línea libre anterior, ya que su función no es separar bloques de código.
¿Qué pasa con el código que ya tengo escrito?
Te puedes preguntar si merece la pena repasar todo el código que ya tengas escrito en una aplicación para aplicar un nuevo criterio de comentarios, sea éste u otro.En principio creo que no es necesario invertir ese tiempo, pero lo que sí haría es aplicar el nuevo criterio cada vez que edito un código antiguo. Esto ayuda a saber que ese código ha sido modificado y con el paso del tiempo podrás conseguir que la mayoría de los procesos más importantes de la aplicación tengan el nuevo criterio aplicado.Como Velneo vERP es una plantilla y, por lo tanto el código es lo más importante ya que es un producto para el desarrollador, sí haremos el esfuerzo de revisar todos los procesos, funciones, manejadores de evento y eventos de tablas aplicando el nuevo estilo.
Feedback
Estaremos encantados de recibir cualquier feedback para aportar mejoras o para confirmar que te gusta alguna parte o todo el criterio de aplicación de comentarios.
