Guía para escribir buenos comentarios de código

• Rol de los comentarios de código:

  • Los comentarios de código van más allá de explicar “qué hace el código que uno escribió”; también documentan decisiones de diseño, trade-offs y otros aspectos analizados
  • Así explican “qué hizo quien escribió el código y por qué lo hizo de esa manera”
  • Los comentarios de código ayudan a compartir el contexto de las decisiones tomadas durante el proceso de desarrollo en el pasado
  • Esto permite transmitir información del código que es difícil expresar solo con el código

• Importancia de los comentarios de código:

  • Un comentario inline antes de un código complejo les ahorra tiempo a otros desarrolladores que revisarán ese código más adelante
  • A medida que el proyecto evoluciona, dejar el contexto de decisiones tomadas en el pasado ayuda a otros desarrolladores.
  • Si el código es complejo, al menos debería haber un comentario inline de una línea antes
  • Hay límites para transmitir solo con el código diverso tipo de información, incluido el contexto de las decisiones de implementación

• Cómo escribir buenos comentarios de código:

  1. Escribir de forma concisa
     • Escribir comentarios solo cuando sea realmente necesario, incluyendo únicamente la información esencial
       • Cuando el código es inevitablemente complejo
       • Cuando se agregan detalles para aumentar la precisión
       • Cuando falta contexto (por ejemplo, al usar código de otro repositorio o paquete)
     • Reducir la confusión y la ambigüedad en los comentarios y aportar contexto e información útil
  2. Usar comentarios TODOs/FIXMEs
     • Los comentarios TODOs/FIXMEs son una forma de indicar que “el trabajo en una parte específica del código no está terminado o necesita corrección”
     • Escribir algo como “TODO: se debe agregar la funcionalidad XX” antes de una función
     • Si mientras escribes código piensas “tengo que revisar esta parte más adelante” o “esta funcionalidad debe desarrollarse después”, este método permite registrar y dar seguimiento a esos puntos
     • Extensión recomendada: TODO Highlight
  3. No justificar el código con comentarios
     • En lugar de poner comentarios para justificar código incorrecto o poco claro, es mejor reescribirlo
     • Hay código que sí necesita explicación con comentarios, pero también hay código que debe hablar por sí mismo sin depender de ellos
  4. Aprovechar la IA
     • Si usas un generador de comentarios con IA, puedes crear comentarios con un formato consistente según ciertos estándares
     • Esto permite mantener la consistencia de los comentarios en todo el proyecto y mejorar la legibilidad del código
     • Generador de comentarios con IA recomendado: Readable

[penza1]

Si parece que hace falta un comentario,
quizá valga la pena pensar si el código no está mal en primer lugar.

Un comentario que no acompaña el ciclo de vida y la funcionalidad del código puede terminar generando confusión para el desarrollador que lo vea en el futuro, o incluso para uno mismo.

Aunque el contexto del pasado ya no tenga relación con el presente o incluso haya terminado provocando errores,
esa frase con el contexto pasado puede hacer que uno dude en modificar lo actual o que termine desviándose para resolverlo con otra estructura,
y hasta puede provocar más errores...

Por experiencia, no hay tantos comentarios que realmente permitan entender por qué algo estaba bien en ese momento pero ahora está mal....

[ironlung]

Gracias por compartir una opinión tan valiosa. Al pensar en lo que comentaste, siento que también hace falta esforzarnos por cuestionar cuidadosamente la necesidad de los comentarios, incluso para el desarrollo del código. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Mientras veo esto, también intento no abusar de los comentarios.

[ironlung]

¡Gracias por compartir un excelente video! :)

[iamchanii]

Por muy bien pavimentado que esté un camino, creo que las señales siguen siendo indispensables. Por eso, últimamente estoy intentando convertir en un hábito el escribir comentarios.

[ironlung]

Gracias por compartir tus ideas en los comentarios. Al pensar en lo que mencionaste, me doy cuenta de que los comentarios también son una forma importante de escritura técnica, así que me hace volver a los principios básicos de la redacción. :)

[balak]

Creo que lo mejor es escribir el código de forma que se entienda incluso sin comentarios.

[ironlung]

Sí, creo que lo primero es mantenerse fiel a lo básico. Gracias por el comentario. :)