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