Comentar el código, un gran enemigo

Hola Laravelos, como estás? Como están llevando el Corona virus? En mi caso estoy trabajando 100% remoto y la verdad que no es algo que me agrade mucho, pero bueno, hay que hacerlo si o si.

En este artículo me gustaría hablar sobre los problemas que nos puede llegar a traer la practica de comentar el código. Creo que es un gran tema de debate ya que se acostumbra a enseñar en algunas Universidad y colegios que siempre se debe comentar el código para que quede lo más claro posible. Y creo que son más los problemas que los beneficios que nos brinda esta práctica.

Para hacer este artículo me apoyare en el libro Clean Code de Uncle Bob (Rober C. Martin), que me pareció excelente.

¿Por qué estamos comentando el código?

A muchas personas, como a mí, nos han enseñado que debemos comentar el código para que quede lo más entendible posible y para que cuando otro desarrollador agarre nuestro código lo pueda entender sin problemas.

Pero creo que justamente ese es el problema, sí tenemos la necesidad de comentar nuestro código, es porque ¡nuestro código no se entiende nada!

Una frase que me gusto mucho de Robert C. Martin que lo dice en su libro Clean Code es:

El uso correcto de los comentarios permite compensar nuestra incapacidad para expresarnos en el código.

Y esto me parece algo totalmente cierto. Usamos los comentarios porque no sabemos, o no queremos tomarnos el tiempo de hacer un código expresivo por sí solo.

Algunos programadores tienen la idea de que son mejores programadores por entender algoritmos complicados, pero eso me parece falso. Tú que prefieres entender, este código:

// Comprobar si hay que aplicar descuento especial al producto:
if ($product->price >= 3500 && $product->status === Product::IN_PROMO)

o prefieres este código:

if ($product->applySpecialDiscount())

De esta forma se entiende rápidamente la intención del código (y hasta creamos una función reutilizable 😉). Con tan solo crear un método que digo lo mismo que el comentario que pensábamos escribir, sacamos más probecho.

Los problemas que nos traen los comentarios

Hay varios problemas con los comentarios pero principalmente es que los desarrolladores no se preocupan en mantenerlos. El código cambia y evoluciona a travez del tiempo pero los comentarios no siempre siguen ese ritmo, no siempre pueden hacerlo y suelen separarse del código que describen y se convierten en algo que nadie se anima a tocar.

Comentarios Incorrectos

Vamos a mencionar 3 de los que me parecen los peores tipos de comentarios que suelen tener los código y que deberíamos evitar a toda costa.

1 . Comentarios redundantes

Estos tipos de comentarios suelen estar en la cabecera de las funciones o métodos y explican exactamente qué es lo que hace el código. Por ejemplo:

// Método que devuelve ejecuta una excepción si el producto es null.
public function existsProduct(Product $product): void
{
    if ($product === null) {
        throw new Exception();
    }
}

¿Qué esta explicando el comentario que ya no se entienda leyendo el código? No nos brinda más información que el código, ni tampoco nos transmite la intención, ni la lógica. Tampoco se lee más fácil que el código mismo. Estos comentarios solamente ensucian nuestro código y por lo tanto deberíamos evitarlos.

2. Si el código es feo, no lo quieras maquillar con comentarios

Muchas veces nos ponemos a escribir un buen pedazo de código y mientras lo vamos escribiendo sabemos que es confuso y pobresito del próximo desarrollador que vaya a agarrar esto!

Entonces, nos apiadamos de nuestro futuro colega (que podríamos ser nosotros mismos) y empezamos a comentar todo el código. ¡Error, mejorar limpialo!

El código claro y expresivo es mucho mejor que el complejo y con múltiples comentarios. En lugar de perder tiempo escribiendo comentarios explicando el desastre que hicimos, dedique ese tiempo a solucionarlo.

3. Código comentado

Este creo que es el peor de todos. No hay nada mas molesto y confuso que el código comentado. Por favor, no lo hagan nunca!

Imagina que te han dado este código para agregar una regla de validación. Se te van a cruzar muchas preguntas, como ¿por qué el resto de las reglas están comentadas? ¿debería descomentarlas y agregar la mía? ¿o descomento todo, borro las reglas que están y agrego la mía? ¿o es que esta ahí mi regla y solo tengo que descomentar?

Hasta que te das cuenta que el método tiene inyectado un FormRequest y es ahí a donde tienes que agregar tu regla de validación 🤦‍♂️.

Y otros casos peores en donde se comentan una linea de código y uno no sabe si esa linea es importante o si se comento porque en el futuro se utilizarán, etc.

Mi recomendación es, apenas veas código comentado, eliminalo! No te preocupes, no es nada importante y si lo fuera, estamos en el siglo XXI y existen controles de versiones para que podamos recuperarlo.

Los comentarios que si son útiles

Vamos a mencionar los comentarios que nos aportan valor y nos ayudan realmente.

1. Comentarios con PHPDoc en API públicas

Estos tipos de comentarios son los mas útiles que podemos hacer. ¿A quien no le gusta una API bien documentada? Los comentarios de PHPDoc nos ayudaran tanto a los desarrolladores como a los clientes que utilicen nuestra API pública. Pero tengan cuidado, ya que PHPDoc nos genera comentarios automáticamente y aveces pueden ser comentarios amplios y ambiguos. Y nunca se debe utilizar para clases y funciones de código no publico.

2. Advertir a otros programadores

A veces es muy útil advertir a los futuros programadores sobre determinadas circunstancias. Por ejemplo, el siguiente comentario le informa al desarrollador porque el caso de prueba esta desactivado.

Con un guion bajo al comienzo del nombre del método provoca que desactivemos el test y dejamos un comentario para que el futuro programador si tiene que hacer esa prueba sepa que le va a llevar tiempo.

3. Comentarios TODO

A veces conviene usar notas en forma de comentarios como son los //TODO. En el siguiente ejemplo, el comentario TODO explica porque la función tiene una implementación incorrecta y cuál sería su posible solución:

// TODO: devolución fake. Debería retornar el total del carrito.
public function calculateTotalCart(Cart $cart): float
{
    return 182.90;
}

Los comentarios TODO son utilizados como recordatorios para que el programador sepa que tareas le esta faltando finalizar. También puede ser utilizado para buscar un mejor nombre a la función, eliminar código obsoleto o para realizar un cambio que dependa de un evento en particular.

Muchos IDE detectan los comentarios TODO para que los encontremos rápidamente y no nos olvidemos de ninguno. Pero no abuces de los TODO y siempre examinalos y eliminalos a penas hayan cometido su objetivo.

No usar comentarios si puedes usar funciones o variables

Como recomendación general, siempre escribe funciones y métodos con nombres explicativos, que describan su función e intención. Como así también variables que describan su contenido.

Conclusión

Hay mucho más por saber sobre los comentarios y como utilizarlos correctamente. ¿Tu eras de llenar tu código de comentarios? Déjame tu comentario y si quieren saber más te recomiendo leer el libro de Uncle Bob. Nos vemos en la próxima.