Nombres y comentarios en la programación

Formación, práctica y constancia son tres de los pilares básicos en los que se sustenta la evolución de cada desarrollador. En ocasiones debemos aprender conceptos complejos de asimilar o de aplicar como parte de este proceso. Sin embargo, en otras ocasiones, son sutiles detalles los que nos hacen mejorar.

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.

Comentarios y nombres de elementos

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):

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

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:

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

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:

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

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:

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

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

<br>
private float suplierPriceOfList;<br>

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:

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

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:

<br>
...<br>
if(manualDiscountIsApplyed())<br>
{<br>
   ...<br>
}<br>
...<br>

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

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

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.

 

Deja un comentario

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