Comentarios a evitar al programar

En muchas ocasiones utilizamos los comentarios casi para cualquier cosa, y siendo honestos, es que se prestan a ello y además podemos sacarle mucho partido. El problema es cuando permitimos que los usos alternativos perduren en el tiempo, pues lo único que conseguimos con ello es ensuciar el código.

Comentarios a evitar en la programación

Por supuesto que podemos utilizarlos para ayudarnos a debugar,  para ponernos notas, recordatorios o ToDos en en código y mil usos más. Pero los comentarios tienen un único objetivo que es aclarar la intención de un determinado bloque de código, y deberemos ceñirnos a este objetivo para garantizar la limpieza y la mantenibilidad de nuestros fuentes. Todo uso que se aleje de este objetivo (o de la documentación del código) no debe perdurar en el tiempo.

Así que a continuación veremos algunos usos inadecuados de los comentarios que están muy extendidos y que deberíamos evitar.

Este artículo forma parte de una serie que trata de una forma más amplia el uso de los comentarios en la programación, y en la que el artículo Introducción a los comentarios en la programación utilizaremos como índice.

Código comentado

Cuando estamos trabajando en un proyecto es bastante habitual encontrarnos con código fuente comentado. Suele ocurrir que comentemos  un pedazo de código por un motivo temporal y no realicemos una limpieza posterior, con lo que queda ahí para la posteridad. Otro motivo bastante habitual es que realicemos un cambio en el código, no dispongamos de un software de control de versiones y no queramos perder el código original.

Sea cual sea el motivo, ¿qué debe interpretar un desarrollador cuando se encuentra un código comentado? ¿Lo ignora? ¿Lo compara o lo interpreta e intenta relacionarlo con el código no comentado? ¿Qué se supone que debe hacer?

Debemos ser limpios y no dejarnos fragmentos de códigos comentados en nuestros fuentes, y si no disponemos de un software de control de versiones deberíamos darle la máxima prioridad a incluir uno en nuestro proyecto. Puedes ver las entradas Instalar y configurar Git en una Raspberry Pi con Ubuntu Mate o Crear un repositorio remoto en Git desde archivos locales.

Identificación de modificaciones

Un uso menos extendido pero con el que he tropezado en alguna ocasión es una versión “sofisticada” del punto anterior. Realizamos una modificación, comentamos el código original e incluimos ciertos datos como el nombre del desarrollador, la fecha en la que se realizó el cambio y el motivo por el que se hizo.

Veamos el siguiente ejemplos:

...
// J.J. 15/10/2017
// Bug: no permitía nombres de 8 caracteres
// if($userName > 8) {
if($userName >= 8) {
   ...

La molestia visual es evidente, además que que nos llevará más tiempo leer y comprender 4 líneas que una:

...
if($userName >= 8) {
   ...

Siempre existen circunstancias alrededor de un proyecto, pero de nuevo, si éste no tiene software de control de versiones todos nuestros esfuerzos deberían centrarse en conseguirlo.

Código para debugar

Esto ocurre en mayor medida, aunque no exclusivamente, en proyectos de desarrollo web. Para ayudarnos a debugar nuestro software incluimos líneas extra de códigos que realizan una tarea determinada. Una vez completado el debug las comentamos y permanecen como partes del código fuente eternamente. Esto no hace más que ensuciar el código, la persona que vuelva a tocar esos fuentes probablemente no necesitará debugar en ese punto, o lo hará de otra forma, así que seamos limpios y borremos este tipo de comentarios.

Además, otro hecho que ocurre, es que si continuamente encontramos comentarios que no añaden valor, acabaremos por ignorarlos todos, ¿por qué tenemos que tropezarnos con comentarios de este tipo en el código?

...
/*
echo '<pre>';
printr($var);
echo '</pre>';
die();
*/
...

Pero sobre todo, asegúrate de disponer de herramientas para debug. Cuando programamos en Java, C++, Basic, C#, etc. no concebimos desarrollar sin herramientas de debug adecuadas, que por lo general vienen incluidas en las IDEs.  Así que si eres desarrollador web, asegúrate también de disponer de éstas herramientas. En este mismo blog tenemos una entrada sobre cómo Debugar PHP con Netbeans y XCode. Para debugar Javascript también tienes múltiples opciones con herramientas como Chrome DevTools o la consola de Mozilla Firefox.

ToDos y notas de trabajo

En ocasiones nos ponemos notas al programar, yo por ejemplo en ciertas situaciones  incluyo alguna línea del tipo:

...
// todo: añadir validación de longitud máxima al nombre
if($userName >= 8) {
...

Existen IDEs que traen soluciones para este tipo de notas, también existen programas que pueden ayudarnos a gestionar estas notas de forma muy efectiva. De cualquier forma, si te gusta trabajar con este tipo de comentarios asegúrate de borrarlo una vez que hayas finalizado la tarea, y si no la vas a terminar, el código fuente no es el lugar dónde indicar las tareas pendientes de completar, así que mejor busca una alternativa.

Concluisión

A pesar de que los comentarios lo aguantan todo, debemos de ser estrictos y hacer un buen uso de ellos, o de lo contrario nunca tendremos un código limpio. Como hemos podido ver, con un software de control de versiones y  alguna herramienta para gestionar tareas pendientes podemos reducir drásticamente el número de comentarios inadecuados.

Seguro que tú también te has encontrado con muchos tipos de comentarios inadecuados, ¿de qué tipo eran? ¿qué herramientas utilizas para evitar estos comentarios?  Como siempre me gustaría conocer tu experiencia.

Contenido relacionado

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *