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

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

César Díaz Alcolea
Comentarios en el código: sí o no- Refactoring & Clean Code

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.

Más de 300 empresas confían en nosotros

Oesia
Vass
Everis
Ayesa
Altran
Ibermatica
Atmira
GFI
Accenture
GMV
Concatel
Telefonica
Caser
Banco de España
kpmg
Mapfre
Randstad