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
Estaré encantado de recibir cualquier feedback para aportar mejoras o para confirmar que te gusta alguna parte o todo el criterio de aplicación de comentarios.
Hola, Jesús, por favor, valoren la posibilidad de que estas lineas de comentarios sean marcadas ‘en verde’ , automáticamente por el vdeveleop, (por ejemplo al guardar) que revise el código y marque ‘en verde’ las lineas Rem y las libres. Gracias.
Hola Miguel.
Gracias por tu comentario.
Me encanta que pongáis comentarios en mi blog, pero por favor, debéis distinguir claramente que este es mi blog «personal», este no es un blog de Velneo, si tienes ideas de mejora aquí podéis comentarlas, me parece perfecto, pero si queréis que se escuchen debéis usar los canales que Velneo pone a disposición de los desarrolladores como es el foro de ideas, por ejemplo.
Respecto a lo comentas, ya lo he respondido también en twitter. No le veo sentido a la idea de que al «guardar» se revise TODO el código de tu aplicación, TODAS las líneas una a una para ver si es un comentario sin «comentar en verde». A que cuando programas no se te ocurre que al cerrar el usuario la aplicación se repase todos los movimientos de almacén que pueden ser miles, cientos de miles o millones para actualizar las existencias. ¿No tiene más sentido que se haga en el momento en que se graba el movimiento de almacén? Pues aquí debería ser igual, si el editor hiciese eso automáticamente debería hacerlo cuando escribimos la línea de comentarios.
Pero hay que pensar que a lo mejor no todos los programadores lo quieren comentado en verde. Puede que a otros les guste en negrita.
Lo cierto es que escribir el REM o añadir un libre y pulsar Shift+F6 es casi instantáneo, pero si algún día vDevelop nos los facilita bienvenido sea, mientras tanto, seamos ágiles usando nuestro editor y no usemos el ratón para comentar líneas.
Un cordial saludo.
Jesús.
Visto así, estoy de acuerdo contigo..
Igualmente.
Miguel.
Buenas es la primera vez que visito esta web y me he decido a comentar.
Me gusta este blog. Que ¿temautiliza? me gustaria poder utlizarlo para mi sitio pero no lo encuentros.
¿Es algún CMS como Budypress?
Si no molesta, no encuentro ningún marcador social como Digg creo que deberiais tener alguno.
Yo uso RSS dado que es facil de usar