La elección de los nombres de los distintos elementos que intervienen en la programación es una de esas tareas que si bien no es técnicamente compleja, puede suponer un antes y un después en cuanto a la calidad del código que generamos.

En esta entrada veremos cómo la elección de nombres adecuados puede contribuir a reducir el número de comentarios necesarios en el código fuente, y por lo tanto a mejorar su limpieza, comprensión y mantenimiento.

Este artículo es el cuarto de una serie de entradas dedicados a los comentarios y cuyo índice podemos encontrar en la entrada Introducción a los comentarios en programación. Así que si estás interesado en mejorar no solo tus comentarios, si no tu programación en general, te recomiendo que leas los tres anteriores: Introducción a los comentarios en programación, Comentarios a evitar al programar, y Mantenimiento de comentarios en la programación.

Nombres descriptivos

Es  bastante común ver funciones o métodos precedidos de un comentario que explica cual es su cometido. Esta situación por si misma no es mala siempre que ayude a entender el código a otros desarrolladores. Sin embargo, en muchas ocasiones la elección de un nombre adecuado puede ser suficientemente descriptiva como para evitar el comentario.

Veamos un ejemplo inspirado en una aplicación TPV (Terminal Punto de Venta):

// Devuelve el precio de un producto valorando descuentos y
// rebajas para un cliente autentificado
private bool getPrice(int itemId, int userId) {
{
   ...
}

Como vemos el nombre del método es descriptivo hasta cierto punto, motivo por el que el comentario ayuda a complementarlo. Pero esto mismo podríamos hacerlo utilizando un nombre más adecuado:

private bool getAuthentificatedCustomerFinalPrice(int itemId, int userId) {
{
   ...
}

En este segundo ejemplo al leer el nombre del método sabemos exactamente que esperar de él, así que no es necesario el comentario.

Hemos podido utilizar esta técnica sin ningún problema porque cumplimos la regla que establece que cada función debe hacer una única cosa. Si no la cumplimos e intentamos escoger un nombre descriptivo nos encontraremos con nombres excesivamente largos. Veamos un ejemplo siguiendo el hilo anterior pero en esta ocasión el método realizará dos tareas:

private bool identifyIfCustomerIsLoggedAngGetFinalPrice(int itemId, int userId) {
{
   ...
}

Cuantas más cosas haga el método, más largo y difícil de elegir será el nombre y esto se traducirá en un código poco legible y difícil de trabajar, volviendo a ser necesarios los comentarios.

Y por supuesto que esta técnica es totalmente aplicable a variables y constantes, escogiendo nombre adecuados eliminaremos la necesidad de explicar el objetivo de las mismas con comentarios. No es lo mismo usar nombres poco descriptivos y acompañarlos de un comentario en la declaración:

// Coste de reposición de artículo
private float cost;

Que utilizar nombre descriptivos, prescindir de los comentarios y saber que contiene exactamente la variable en cualquier punto del programa:

private float supplierPriceOfList;

Sustituir un pedazo código por una función

En ocasiones explicamos pedazos de código porque queremos transmitir nuestra intención, porque ayuda a la comprensión de un algoritmo con cierta complejidad, porque nos parece que es engorroso de leer y un comentario lo facilitaría, etc. Pongamos un ejemplo muy sencillo, de nuevo sobre un programa TPV:

// Comprobamos si hemos introducido un descuento manual 
if(
   (item.price  > item.proposedPrice)  &&
   (discount.reason is null) &&
   (item.price != item.proposedPrice * customer.discount)
)
{ 
   ... 
}

El programador que ha escrito este código (yo) ha querido dejar claro que las tres condiciones que ha escrito tenían como intención averiguar si se había introducido un descuento manual.

Pero quizás sea mucho más claro leer el código de esta manera:

if(manualDiscountIsApplyed())  
{
   ...  
}

Y para ello solo tenemos que encapsular ese bloque lógico en otro método con un nombre adecuado:

private bool manualDiscountIsApplyed()  
{  
   bool discountIsApplied = false;  
   if(  
      (item.price > item.proposedPrice) &&
      (discount.reason is null) &&
      (item.price != item.proposedPrice * customer.discount)  
   )  
   {  
      discountIsApplied = true;  
   }  
   return discountIsApplied;  
}  

Aunque si lo pensamos un instante lo único que hemos hecho ha sido un uso correcto de la programación orientada a objetos, el resto ha sido de nuevo la elección de un buen nombre.

Conclusión

En el desarrollo de software, como en prácticamente todo, cuanto más simple y breve sea la solución, mejor. Lejos de de extender y adornar el código debemos procurar sintetizar y aclarar todo lo posible de forma que sea sencillo de comprender por si mismo, y para ello una elección correcta de nombres es fundamental.

Y como es habitual, sería muy interesante conocer tu punto de vista, ¿qué otra técnica utilizas tú para mejorar la legibilidad del código y evitar comentarios innecesarios? Comparte tu experiencia en un comentario.

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.

[the_ad id=»1018″]

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.

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.

A pesar de que en un primer instante pueda parecer un asunto un tanto superficial, los comentarios en la programación son un tema muy interesante, no por su complejidad, sino porque un correcto uso de ellos puede marcar la diferencia en cuanto a limpieza, facilidad de comprensión del código y su mantenimiento.

Objetivo de los comentarios

Los comentarios, cuando hablamos de programación, son bloques de texto escritos en lenguaje natural que están incluidos dentro del código fuente, que el compilador ignora y que por norma general están destinados a que sea el programador el que los interprete.

El objetivo principal de un comentario es dejar constancia en el código fuente de la intención de un determinado bloque de código. Esto es especialmente útil cuando más de un programador tiene acceso al mismo código o para recordar en el futuro por qué tomamos determinada estrategia para el código al que hacemos referencia.

[the_ad id=»1018″]

Existe también un segundo objetivo muy extendido y de gran utilidad que es para documentar el código. Siguiendo algunas reglas que varían en función de la herramienta, ciertos comentarios pueden ser interpretados por aplicaciones que generan documentación de manera automática. Algunos ejemplos de estas aplicaciones son Javadoc en Java o Doxygen en PHP.

Características de los comentarios

Así que dejando al margen del tema de la documentación, para que un comentario aporte todo el valor que se le presupone debe cumplir algunas características.

1. Complementar al código. Un buen comentario debe transmitir la intención del programador, el concepto, el motivo, la estrategia, pero nunca traducir a lenguaje natural ni explicar el código que hemos escrito, eso ya lo sabe hacer la persona que lee el código.
2. Ser claro y comprensible. Escribimos los comentarios para que otros, o nosotros mismos en el futuro, los lean, así que asegurémonos de que cuando lo hagan comprendan perfectamente el mensaje que les estamos transmitiendo. ¿Cuántas veces escribiste una nota que al leerla pasado cierto tiempo no eres capaz de entenderla?
3. Ser conciso. No hace falta extendernos o explicar hasta el último detalle, cuanto más concisos seamos más fácil será comprenderlo e invertiremos menos tiempo en ello.

Profundizando en los comentarios

Realmente esta entrada no era más que una excusa para introducir y dar paso a otros artículos relacionados con los comentarios.

Estos artículos guardarán también cierta relación con una entrada que escribimos hace tan solo unas semanas atrás: ¿A qué huele el código fuente?, tratando el código oloroso y en la que hacíamos referencia a los comentarios como una posible fuente de olores.

Así que a continuación tenéis todas esas entradas que durante las próximas semanas iremos publicando:

1. Comentarios a evitar
2. Mantenimiento de comentarios
3. Comentarios y nombres de elementos

Conclusión

Los comentarios, lejos de lo que pueda parecer cuando no se tiene la suficiente experiencia, son un tema que a pesar de su simplicidad pueden marcar la diferencia en nuestro código y al que merece la pena dedicarle cierto tiempo.