Mantenimiento de comentarios en la programación

Uno de los aspectos más delicados con respecto a los comentarios es la limpieza. Al contrario de lo que sucede con el propio código fuente, los comentarios no son procesados por el compilador, lo que quiere decir que éste no nos avisará si hay algo incorrecto o poco fiel con respecto a la realidad.

Comentarios en programación, mantenimiento

En multitud ocasiones he visto y he escrito comentarios que ensucian el código y que en el mejor de los casos solo son una molestia visual. En cambio, otras ocasiones, me he tropezado con comentarios que pueden llegar a confundir al programador, sembrar la duda en él o hacer que gaste más tiempo del necesario intentando comprender la discrepancia entre el comentario y el código.

Esto ocurre principalmente porque al igual que sucede con el resto del código fuente, los comentarios requieren de un mantenimiento. Y para conseguirlo es necesario que el desarrollador sea mucho más estricto que con el resto del código: si el compilador no alerta tendremos que ser nosotros quien garanticemos que son correctos. Y el problema radica en que incluso si los comentarios son un verdadero desastre, si el código es correcto el programa funcionará, y muchas veces eso nos basta.

Así que en esta entrada trataremos algunos aspectos que hemos de tener en cuenta a la hora de mantener nuestros comentarios. Este artículo pertenece a una serie cuyo índice podemos encontrar en la entrada Introducción a los comentarios en programación.

Comentarios a evitar

Hace una semana publicamos una entrada titulada Comentarios a evitar al programar.  En ella hablábamos de los comentarios que no deberíamos hacer que perduren en el código, y podemos decir que éste es el primer paso que debemos de tomar a la hora de mantener los comentarios. Haciendo un breve resumen hablamos de:

  1. Código fuente comentado
  2. Identificación de modificaciones
  3. Código para debugar
  4. ToDos y notas de tareas pendientes

Si todavía no has leído este artículo te recomiendo que lo hagas antes de continuar con el siguiente punto.

Copy & Paste

¿Cuantas veces has copiado y pegado un fragmento de código en el que existen comentarios? Pongamos el ejemplo de un método cualquiera, queremos crear otro bastante similar  y optamos por copiar y pegar en lugar de escribir desde cero. Acto seguido modificamos el nuevo método, pero, ¿cuantas veces hemos dejado un comentario sin modificar haciendo referencia al funcionamiento del método original?

Como primer planteamiento me preguntaría si el comentario es realmente necesario, pues si no le has dado la importancia adecuada quizás es simplemente porque no la necesita y puede ser eliminado. Pero en caso de que deba ser mantenido no olvides actualizarlo si es necesario. De lo contrario estarás mintiendo al programador que lo lea.

Modificaciones en el código

Lo más habitual cuando modificamos unos fuentes es que estemos alterando de una u otra manera su funcionamiento. Si existe un comentario realizado sobre el bloque de código que estamos modificando, deberemos de verificar que tras la modificación el comentario sigue siendo tan necesario y válido como era antes de cambiar una sola línea. De lo contrario volveríamos a tener un comentario erróneo.

Imaginemos que tenemos un método userIsAuthenticated() que devuelve la ID de un usuario en caso de que esté autentificado y 0 en caso de que no lo esté.  Imaginemos que modificamos ese método para que devuelva true si está autentificado y false si no lo está, y a su vez creamos otro método getUserId() que devuelve la ID de un usuario autentificado. En caso de que existiera algún comentario en el método original o en alguna llamada al método también debemos de modificarlo para que refleje el nuevo comportamiento.

El precio de no mantener los comentarios

Imaginemos qué estamos revisando un código escrito por otro desarrollador, y a medida que avanzamos notamos que los comentarios son superfluos y en muchos casos imprecisos e incoherentes con respecto al código, ¿qué ocurriría? Probablemente o los ignoraríamos por completo o seguiríamos leyéndolos a regañadientes.

Pero ¿que ocurriría si en lugar de ignorarlos tomamos por bueno la información de los comentarios en lugar de la realidad del código? La respuesta dependerá de cada situación, y en cada una de ellas intervendrán muchos factores, así que dejo esta respuesta a tu criterio, pero personalmente ninguna situación de las que soy capaz de imaginar es positiva.

Refactorizar comentarios

Hace no mucho escribíamos también sobre el código oloroso en la entrada ¿A qué huele el código fuente? y sobre refactorización en la entrada Refactorización de código.

La refactorización de los comentarios, que hoy estamos llamando mantenimiento, es tan importante como la del propio código. No basta solo con seguir los manuales de buenas prácticas al escribir nuevo código, debemos limpiar y corregir los comentarios irrelevantes, incomprensibles, imprecisos, incoherentes o erróneos que nos encontremos como parte de nuestra labor.

Si decidimos no refactorizar la primera consecuencia será que asumiremos que tanto nosotros como el resto del equipo que trabaje con ese código vamos a tener que convivir con comentarios erróneos. Y la segunda consecuencia que se dará con bastante probabilidad, es que el equipo se contagiará de la dejadez del código y comenzará a emplear malas prácticas, lo que suele acabar en un problema que crece con el paso del tiempo.

Conclusión

Debemos tratar los comentarios con la misma delicadeza que tratamos el resto del código, pues un código bien comentado facilita el mantenimiento del software y contribuye a evitar la deuda tecnológica.

¿Y tu qué opinas?, ¿crees que existen más situaciones relacionadas con los comentarios que debamos tener en cuenta en el mantenimiento?, ¿tienes algún consejo o recomendación? Sabes que nos gusta leer tu opinión, compártela en los comentarios.

Deja un comentario

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