Cuándo usar comentarios

• El comentario no debe explicar:

  • ❌ El ¿Qué? ⇒ porque el código debe ser Autodescriptivo
  • ❌ El ¿Cómo? ⇒ el código debe ser Autoexplicativo
  • ✅ Sino el ¿Por qué? // Comentar explicando los Criterios, aportando valor

“No comentes código mal escrito, reescríbelo.”
Brian Kernighan

• Si bien, al usar correctamente la nomenclatura, el ordenamiento de nuestras variables, funciones y clases y respetar el principio de responsabilidad única, va a hacer que nuestro código sea mucho más fácil de entender, no significa que se deba dejar de añadir comentarios. Por ejemplo, añadir un comentario sobre alguna librería externa que se haya utilizado.

Pienso que, a veces si son necesarios los comentarios para intentar explicar lógica de negocio que puede llegar a ser confusa y los comentarios pueden dar una idea de lo que hace. Por ejemplo, poner ejemplos en el comentario

Ojo con dejar todo’s por ahi, ja

"Yo comento lo que se me da la gana."
Yo.

Yo pienso que si mi código ya cumple con los principios solid o clean code, será poco necesario por que ya será autoexplicativo, al menos que requiera dar avisó del porque se utilizo alguna librería en particular como lo mencionan o porque se decidido hacerlo de una forma y no de otra.
Saludos!!

Creo que en estos casos es muy recomendable el uso de JSDoc o TSDoc, ya que va a ayudar a la experiencia de desarrollo y a tener una mejor lectura del código.

Creo que el código se debe de explicar en cosas muy importantes, o muy pesadas de entender.

Dentro de la práctica, lo recomendable escribir comentarios para explicar usos o soluciones que le has dado a un código en especifico. Esto puede servir para entendimiento de un grupo de trabajo.