Clean Code – #1. Comentarios (in)útiles ❌

En este microcurso te enseñaré algunos pequeños consejos sobre cómo escribir Código Limpio aplicado a Javascript (y a otros lenguajes de programación). 🧹

De antemano quiero agradecer a quienes habéis dado permiso para utilizar vuestro código para ser analizado. 🥰

¡Y hoy empezaremos por aprender a escribir comentarios!

“Venga ya, qué me estás contando. Si para eso no hace falta saber”.

Sí, ya, eso es lo que tú te crees. Y si no mira lo que dice Ada:

“Más vale un código sin comentar que un mal código bien comentado”.

Ada Lovecode

Piénsalo bien: si un código no se entiende por sí solo, por muchos comentarios que añadamos, quizá es que hemos hecho algo mal, ¿no crees?

Y es que ya lo dijo Brian W. Kernighan:

No comentes el código mal escrito: reescríbelo.

Brian W. Kernighan

¡Empecemos trabajando! 💪🏼

Mira estos comentarios y reflexiona sobre ellos. ¿Te parece que están bien o mal?

//Función que crea un tren

//if (persona.nombre == ‘’) creaPersona();

//Fin while

Sigue adelante con la lección y te sacaré de dudas.

¿Cuándo comentamos mal? ❌

• Cuando comentamos porque debemos explicar código poco comprensible o desorganizado.
• Cuando comentamos demasiado cosas que no es necesario explicar.
• Cuando comentamos el qué o el cómo en lugar de el porqué.
• Cuando dejamos código comentado sin razón.
• Cuando tenemos que comentar dónde terminan las estructuras de control (if, while) porque el código es demasiado largo.

Veamos algunos ejemplos reales de código mal no muy bien comentado:

En este caso Michelle, con toda su buena intención, escribió un comentario que no solo no era necesario sino que además explica qué es lo que hace en lugar del porqué. Cualquiera que conoce el lenguaje sabe lo que hace esta función, ¿no crees?

Nos encontramos el mismo caso en este código de Mikel:

O en este código de Adrián, que no está muy claro por qué está comentado el if:

Y por último aquí este ejemplo de Edu, que comenta algo también evidente:

¿Cómo saber cuándo comentar?📝

• Debemos incluir comentarios cuando hay que añadir textos legales.
• Debemos evitar comentar si no aportamos nada al código porque se entiende solo.
• Debemos reescribir algo que es confuso, demasiado largo o desorganizado en lugar de comentarlo.

En esta ocasión, el mismo Edu nos deja tres buenos comentarios que nos permiten identificar qué tipo de lotería se está gestionando en cada caso. Podría hacerse mejor, pero no es un mal uso de comentarios:

 ¿Y tú eres de los que comentas mucho, poco o nada?

¿Crees que haces comentarios útiles en tu código?

¡Responde con un comentario y cuéntanos, o comparte alguno de tus códigos y ponlo a prueba!