Comentarios en el código, ¿sí o no?

En esta ocasión hablamos de un tema realmente controvertido y que genera bastante polémica entre los programadores, como es el caso de los comentarios dentro del código, ¿son realmente necesarios?

Publicado el 05 de Diciembre de 2019
Compartir

Comentarios dentro del código, ¿sí o no?

Según mi experiencia, cuándo se utilizan comentarios en el código suelen ser poco fiables, y debemos confiar solo en el código.

Hay una frase muy relacionada con esto, que dice:

“El código nunca miente, los comentarios sí.” — Ron Jeffries

Imagen 0 en Comentarios en el código: sí o no- Refactoring & Clean Code

Los comentarios requieren mantenimiento, y muchas veces se empieza a meter comentarios, pero el día de mañana se dejan de mantener, con lo cual el comentario dice una cosa y el código hace otra.

Tipos de comentarios a evitar

  • Evitar marcadores posicionales

Imagen 1 en Comentarios en el código: sí o no- Refactoring & Clean Code

Estos comentarios simplemente añaden ruido, no añaden nada, son comentarios inútiles.

  • No dejar el código comentado en su código base

Imagen 2 en Comentarios en el código: sí o no- Refactoring & Clean Code

Encontrar código que está comentado y que ya no se utiliza, hoy en día no tiene sentido, ya que tenemos el control de versiones, tenemos Git y tenemos un historial de versiones, en el cual podemos buscar el código que teníamos anteriormente.

Dejar trozos de código comentado lo único que hace es añadir ruido y añadir tiempo de lectura a la hora de revisar nuestro código.

  • No dejar comentarios de diario

Imagen 3 en Comentarios en el código: sí o no- Refactoring & Clean Code

Otro tipo de comentarios que hoy en día, teniendo Git, no tienen ningún sentido, ya que acaban siendo una lista de comentarios.

Además, puede llegar el momento en que dejen de añadirse nuevas líneas, y no va a estar en consonancia lo que indica el comentario y lo que dice el código, por lo que al final debemos fiarnos solo del código y hay que tener el código limpio.

Comentarios aceptables

“El uso adecuado de los comentarios es compensar nuestra incapacidad para expresarnos mediante el código” — Robert C. Martin

Existen algunos tipos de comentarios que se pueden considerar medios aceptables, y son los comentarios que tienen complejidad lógica de negocios. En estos casos, los comentarios son una disculpa y no un requisito.

Un buen código vas a ser siempre autodocumentado. Si un comentario te explica lo que el código está haciendo, probablemente sea un comentario inútil, y seguramente, si se retoca un poco el código y se usan buenos nombres para las funciones y variables, probablemente se pueda eliminar ese comentario.

Hay cosas que pueden ser interesantes de comentar, porque sea algo un poco más abstracto, como podría ser por ejemplo comprobar una expresión regular, ya que se puede leer la expresión regular y quizás no se sepa qué es lo que está comprobando.

Puede ser también el caso del uso de un algoritmo de encriptación en vez de otro, o que alguna cosa tenga una dependencia de un tercero y se tenga que hacer una espera, entonces poner ahí ese tipo de comentario que aporta algún valor, podría ser medio aceptable.


Compartir este post

También te puede interesar...

Tecnología

Aprende a crear un Blockchain con JavaScript

18 Mayo 2023 Alfredo Barragán
Tecnología

Comparativa Arduino vs Particle vs Raspberry Pi

11 Mayo 2023 Diego Caceres Solis

Las cookies nos permiten ofrecer nuestros servicios. Al utilizar nuestros servicios, aceptas el uso que hacemos de las cookies. Más Información.