Comentario de código en JavaScript: tipos y mejores prácticas

Introducción

El propósito principal de escribir código es que una computadora pueda interpretarlo como comandos. Sin embargo, también es importante que el código que escribimos también sea fácilmente interpretable por otros desarrolladores.

¿Alguna vez ha vuelto a un proyecto y ha tenido dificultades para comprender la lógica interna? Bueno, probablemente sea porque dicho proyecto no ha sido comentado correctamente.

Comentarios son notas escritas en el código que son ignoradas por el motor JavaScript, lo que significa que no afectan la salida de ninguna manera. Su único propósito es describir cómo y por qué funciona el código para otros desarrolladores y para usted.

En este artículo, veremos cómo comentar código JavaScript, qué tipos de comentarios existen y algunas de las mejores prácticas.

Comentarios de una sola línea

Los comentarios de una sola línea se utilizan generalmente para comentar una parte de la línea o una línea completa de código. Los comentarios de una sola línea en JavaScript comienzan con //. El intérprete ignorará todo lo que esté a la derecha de esta secuencia de control hasta el final de la línea.

Veamos un ejemplo de un comentario de una sola línea en acción:

// Print "Hello World" in the console
console.log("Hello World");

Aquí, estamos usando un comentario de una sola línea para describir lo que está haciendo la siguiente línea de código.
Si aparece un comentario de una sola línea al final de una línea de código, se denomina comentario en línea.

Por lo general, se usan para agregar anotaciones rápidas:

let c = a + b; // Assign sum of a, b to c

Comentarios de varias líneas y cadenas de documentos JavaScript

Si quisiéramos agregar una nota que se distribuye en varias líneas, podemos optar por comentarios de varias líneas o comentarios a nivel de bloque.

Los comentarios de varias líneas comienzan con /* y terminar con */:

/* The following program contains source code for a game called Tic-tac-toe.
It is a paper-and-pencil game for two players, X and O, who take turns marking the spaces in a 3×3 grid. 
The player who succeeds in placing three of their marks in a horizontal, vertical, or diagonal row is the winner
*/

Aquí, se utiliza un comentario de varias líneas para describir tic-tac-toe. Generalmente, los comentarios de varias líneas se utilizan para introducir y explicar una sección de código, donde una sola línea / oración no es suficiente.

A menudo también se puede ver otro tipo de comentario de varias líneas:

/**
* The following program contains source code for a game called Tic-tac-toe.
* It is a paper-and-pencil game for two players, X and O, who take turns marking the
* spaces in a 3×3 grid. 
* The player who succeeds in placing three of their marks in a horizontal, vertical, or 
* diagonal row is the winner
*/

A menudo, estos comentarios pueden incluir información sobre el código de procedimiento, como los parámetros de una función o incluso el autor del código:

/**
* Function that greets a user
* @author   John
* @param    {String} name    Name of the user
* @return   {String}         Greeting message
*/
function greetUser(name) {
    return `Greetings, ${name}!`;
}

Estos comentarios se conocen como DocStrings, ya que son esencialmente cadenas (comentarios) que constituyen la documentación de su código.

Este tipo de comentarios son realmente útiles para otros desarrolladores de su equipo, ya que puede aclarar cuál es la entrada esperada, cuál es la salida, así como a quién contactar si es necesario.

Un beneficio adicional es que puede generar documentación basada en estos DocStrings.

Usar comentarios para depurar

Además de tomar notas, los comentarios también se pueden utilizar para evitar rápidamente la ejecución de código con fines de depuración. Esto es posible porque los motores JavaScript no interpretan el código comentado. Esto se llama como comentando el código.

Si hay una línea errónea que está causando problemas, simplemente podemos «comentarla» para deshabilitarla, sin borrar la línea. Esto se puede combinar con depuradores reales para ayudarlo a evaluar lo que está sucediendo.

Considere el siguiente código:

console.log("Working code");
console.log("Erroneous code);

Si queremos eliminar la segunda declaración, pero no queremos eliminarla para siempre, simplemente podemos comentarla:

console.log("Working code");
//console.log("Erroneous code);

Consejo profesional: En la mayoría de los editores de código, podemos usar el atajo de teclado Ctrl + / para Windows y Cmd + / para que Mac comente una sola línea de código.

Además, también puede comentar secciones enteras si no está seguro de si las eliminará o no:

/*console.log("Entering for loop");
for (let i = 0; i < 100; i++) {
    console.log(i);
}*/

Buenas prácticas de comentarios

En primer lugar, comentar no es una excusa para escribir código ilegible y luego simplemente remendarlo con cinco párrafos de comentarios que lo expliquen. Primero tenemos que enfocarnos en escribir código limpio y autoexplicativo, que luego se puede mejorar con comentarios constructivos.

Utilice comentarios para explicar por qué hiciste algo, no cómo lo hiciste. Si se encuentra explicando cómo hizo algo, entonces es hora de dar un paso atrás y refactorizar su código en algo que se explique por sí mismo.

Otro consejo sería no escribir comentarios que sean obvios y redundantes por naturaleza. Por ejemplo, el siguiente comentario es completamente innecesario:

// Prints out the result
console.log(result)

Hay herramientas útiles, como JSDOC 3 que puede generar documentación, basada solo en los comentarios dentro de su código, que tienen el formato DocStrings descrito anteriormente.

Conclusión

En este artículo, hemos repasado qué son los comentarios y cómo crearlos en JavaScript. Hemos analizado diferentes tipos de comentarios: comentarios de una línea y de varias líneas, así como las cadenas de documentos JavaScript mencionadas.

También hemos visto cómo depurar nuestro código usando una técnica llamada «comentar», y finalmente resumimos algunas buenas prácticas para comentar.