¿Es malo comentar el código?

¿Qué es un comentario?

Un comentario es una línea en el código fuente que los desarrolladores pueden leer, pero que los compiladores e intérpretes ignoran.

¿Cuál es el significado de eso?

Como regla general, "leer" el código es bastante difícil. Y el texto explicativo ayuda a los desarrolladores a "explicar" lo que han escrito a alguien que mantendrá el código en el futuro.

¿Necesitas pruebas? Tomemos este código sin comentarios:

let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);
game.v_Add(bg_a);

Este bloque de código realiza varias funciones. Resultado: los programadores no pueden entender rápidamente qué hace exactamente este código.

Y ahora proporcionaremos el mismo código con comentarios.

// create the alien object.
let o_fac = new BGF()
let bg_a = o_fac.build("ALIEN");
// set Alien details.
bg_a.i_health(100);
bg_a.i_armor(50);
bg_a.i_attack(50);
//add to game
game.v_Add(bg_a);

¿No ha aumentado la legibilidad del código? Esto se debe a que los comentarios describen lo que hace el código, mientras que el propio código muestra cómo se hace.

Los desarrolladores estamos acostumbrados a pensar en términos de “qué”, olvidándonos del “cómo”.

Entonces, ¿resulta que los comentarios explican nuestro código?

Si.

Eso suena bien …

Y ahí está. Pero puedes explicar el código de diferentes maneras. Y comentar es lo peor de ellos.

¿Por qué comentar se convirtió en "lo peor"?

Hay varias razones para esto. Para empezar, no hay garantía de que alguien lea tus comentarios. En la práctica, pocos desarrolladores les prestan atención. Mira esta pantalla de Webstorm. En el esquema de color original, los comentarios están resaltados en gris y completamente anodinos:

Entonces, ¿por qué no iniciar un blog llamado "Por favor, lea los comentarios"?

¡Buena pregunta! Porque no puedes confiar en los comentarios que lees.

Su fuente de verdad será el código ejecutable que usted mismo escriba. Sabemos que el código es verdadero porque en realidad lo hacemos. Los comentarios son una fuente alternativa de verdad, pero no tenemos ninguna garantía de su veracidad como tal.

Como con cualquier sistema con múltiples fuentes de verdad, un desarrollador puede actualizar un código pero olvidarse del otro. ¿Puedes decir honestamente que al corregir el código, realmente lees todos los comentarios y te aseguras de que sean correctos?

Por supuesto que no, esto a menudo se olvida.

Eso es. Así que asegúrese de que solo haya una fuente de verdad en sus sistemas.

Está bien, lo admito, los comentarios no son la mejor solución. Pero nada es perfecto en este mundo. ¿Estás diciendo que hay una mejor opción?

Si. Muéstrame tu comentario y te sugeriré una mejor opción.

¿Qué pasa con los comentarios que describen variables? ¿Estás diciendo que es mejor no usarlos para crear explicaciones variables?

Describir lo que hacen las variables es extremadamente importante. Por lo tanto, asignamos nombres a las variables. Si asigna un nombre significativo a la variable, desaparecerá la necesidad de comentarios. Y es aún mejor explicar su propósito en cada lugar donde se usa la variable. Entonces el mantenedor no tendrá que dejar de leer el código para encontrar una pieza específica con una explicación de la variable. Vea cuánto mejor se ve el segundo código.

// Bad.
let x; // Variable to hold id of car being displayed.
// Good.
let displayedCarId;

Este mismo principio se aplica a las funciones, ¿verdad?

Si. Nombre funciones y parámetros basados ​​en su propósito. Una vez hecho esto, no hay necesidad de comentar el estilo del encabezado de la función inmediatamente.

¿Qué pasa con el código anterior? ¿Los comentarios describían bloques de código que colectivamente proporcionan su funcionalidad? Obviamente, un solo nombre no nos ayudará, ¿verdad?

No, solo nos ayuda. Varias líneas de código que realizan una acción específica juntas se pueden traducir en una función con el nombre adecuado. Echa un vistazo aquí:

let alien = alienFactory
              .createAlien()
              .withStats({
                  health: 100,
                  armor: 50,
                  attack: 50
                })
              .getAlien();
game.add(alien);

¿Ves cómo este código se traduce en una función que describe su propósito? Lo mismo se aplica al código estático. No necesita mayor explicación; el código hace lo que dice.

Otra ventaja de usar la función en este ejemplo es que se ocultan todos los detalles innecesarios. El mantenedor no tiene que preocuparse por cómo funcionan las funciones que no están relacionadas con un solo cambio en el código. Y así el código se vuelve más fácil de entender.

Además, el mantenedor no ignorará el nombre de la función, mientras que el comentario puede olvidarse. El nombre de la función ya forma parte del código. Por lo tanto, al leer todo el código, se leerá tanto el nombre como la llamada a la función.

¿Qué pasa si tengo que trabajar duro para optimizar algún código? ¿Puedo referirme a los comentarios entonces?

Si.

¿Detener Qué?

Somos  desarrolladores de software . Y todos los desarrolladores tienen herramientas. Los comentarios son las mismas herramientas que las funciones con nombres de variables. Pero ningún remedio resuelve todos los problemas a la vez. Y una herramienta nunca es suficiente. Si cambiar la estructura del código no mejora su legibilidad, vale la pena recordar los comentarios.

¿Entonces los comentarios son buenos?

¡No, los comentarios apestan! La mayoría de los comentarios que encontré en la práctica no son buenos. Básicamente, los comentarios se utilizan para disculparse por:

Denominación incorrecta de variables o funciones.

la complejidad o longitud del código.

La afirmación de que los comentarios son malos no es la verdad última. Más bien, es una observación puramente práctica. Pero incluso para comentarios hay casos raros de uso adecuado.

Traducción del artículo Sam Fare : ¿Los comentarios de código apestan?