Documenta
Última actualización
Última actualización
La principal labor de un desarrollador es escribir buen código. Las mejores aplicaciones siempre tienen bajo el capó buen código. No es posible construir buenas aplicaciones, con buena nota en funcionalidad, usabilidad y rendimiento escribiendo mal código.
Cuando estamos escribiendo código debemos ser conscientes de que ese código debe durar muchos años, en ocasiones decenas de años. Además, ese código va a ser mantenido por nosotros mismos o por otros desarrolladores. Por lo tanto debemos mimarlo para que sea fácil de entender, mantener y mejorar.
Por estos motivos no debemos correr a la hora de escribir código y debemos emplear el tiempo necesario para hacer un buen naming, buenos comentarios y código de calidad. A igualdad de rendimiento el mejor código es el más sencillo de entender y mantener.
En la codificación todo es importante, pero para facilitar su legibilidad debemos escribir buenas descripciones de objetos que nos faciliten entender que hace el objeto o para que ha sido creado, utilizando el menor número de palabras posibles.
Tras copiar un objeto el siguiente paso debería ser modificar su descripción, cuando no lo hacemos nos con objetos que teniendo diferentes identificadores tienen la misma descripción lo que dificulta su mantenibilidad.
Un código sin comentarios nos obliga a leer todo el código para entender qué hace. Además de ser más lento para el programador que lo mantiene, es muy fácil que no se llegue a conclusiones acertadas ya que no siempre es obvio todo lo que se programa. Por este motivo es muy importante comentar código y, sobre todo comentarlo bien.
Comentar bien el código implica no escribir comentarios obvios que no aportan valor, ni comentarios tan extensos que cuesta lo mismo leerlos que leer e interpretar el código. Un buen comentario debe ser preciso, conciso y estar ubicado en el lugar adecuado.
Todo proceso, función o manejador de evento debería comenzar con un comentario que describa lo que hace. Es cierto que es redundante en muchos casos con la propiedad descripción de propio objeto, pero debemos entender que no siempre tenemos a la vista el código y sus propiedades, por eso es importante disponer del comentario en el inicio del código.
En un equipo de desarrollo no hay nada mejor que conseguir que todos los programadores escriban el código aplicando los mismos criterios para el naming, descripciones, comentarios y codificación. Con el fin de facilitar esta homogeneidad es conveniente disponer de un estilo de comentarios. A continuación se describe un estilo sencillo y fácil de recordar. A continuación se muestra un ejemplo de cómo queda el código aplicando el estilo de comentarios.
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 matizaciones a la hora de aplicarlos en función de la localización.
A vamos a reparar 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.
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.
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á:
Se considera importante para el desarrollo en equipo se aplicará el siguiente formato:
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.
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.
Cuando hay bloques de código que se escriben con sangrado debido a comandos de instrucció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.
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.
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 incluirá una línea libre anterior, ya que su función no es separar bloques de código.
Cuando editamos código en un manejador de evento, proceso, función o evento de tabla hay muchos programadores que tienen el hábito de añadir líneas vacías para luego ir rellenando el código, eso está bien siempre y cuando una vez terminado de escribir el código eliminemos las líneas “Libre” no comentadas.
El motivo de no dejar líneas libres es doble, por un lado porque una línea no comentada se evalúa aunque sea para saber que no hay ningún comando de instrucción a ejecutar y por otro lado da la sensación de código incompleto no teniendo claro si el código está terminado o queda algo por programar.
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. En principio no es necesario invertir ese tiempo, pero lo que sí es conveniente es aplicar el nuevo criterio cada vez que edites 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.
