Cómo agregar comentarios en JavaScript

En este tutorial vamos a ver cómo cómo puedes agregar comentarios en archivos JavaScript.

Cuando programas, es habitual dar más valor al código que a las posibles personas que lo revisarán posteriormente. En ocasiones, serán otras personas, pero muchas otras veces serás tú mismo. Por ello, es importante comentar el código de modo que sea más fácil de entender, tanto para ti como para los miembros de tu equipo.

Hay quien dice que no es necesario agregar comentarios, que un código bien estructurado no los necesita. Si bien esto es cierto en parte, también es cierto que las tendencias en la estructura del código y los patrones de diseño cambian continuamente, y cada vez lo hacen más rápido. Por ello, un código que incluye comentarios siempre será más fácil de entender, evitando que cada uno de los desarrolladores que lo revise tenga que dedicar minutos u horas a entenderlo.

Qué es un comentario

Un comentario no es otra cosa que una anotación en el código fuente de una aplicación. Los comentarios son ignorados por los intérpretes y por los compiladores, por lo que no tienen efecto alguno en las aplicaciones resultantes. Los comentarios pueden ser de gran ayuda a la hora de explicar lo que hace el código o cómo debe modificarse.

Como desarrollador, en ocasiones resulta frustrante modificar el código escrito por otra persona, especialmente cuando no ha sido comentado. Por otro lado, también es muy habitual olvidarse de lo que hacía tu propio código una vez comienzas a desarrollar otra aplicación y pierdes del contexto del mismo. Además, si te acostumbras a comentar el código, crearás un buen hábito que otros desarrolladores amularán.

Sintaxis de los comentarios en JavaScript

En JavaScript existen dos modos de agregar comentarios, pudiendo agregar comentarios que ocuparán una sola línea o varias líneas.

Para agregar comentarios que ocupen una sola línea tendrás que agregar dos barras inclinadas // tal y como ves en este ejemplo:

// Esto es un comentario

Todos los caracteres de la línea que se sitúen después de los caracteres // formarán parte del comentario, siendo ignorados por JavaScript.

Para agregar comentarios que ocupen varias líneas, también conocidos como comentarios multilínea, tendrás que usar los caracteres /* para iniciar el comentario y los caracteres */ para cerrarlo. Todo lo que esté entre esos dos conjuntos de caracteres formará parte del comentario, creando así un comentario en bloque:

/* Esto es un
comentario
multilínea */

Todo el texto que se incluya entre los caracteres /* y */ será ignorado por JavaScript. Puede que esta sintaxis te resulta familiar, ya que es la misma que se utiliza para agregar comentarios en CSS.

Tipos de comentarios en JavaScript

En JavaScript, tal y como hemos explicado, existen los comentarios en línea y los comentarios multilínea. Vamos a ver cómo se usan y en qué casos se usan unos u otros.

Comentarios en línea

Los comentarios en línea son aquellos que ocupan una línea. Pueden declararse en cualquier parte de la línea mediante lo símbolos //. El texto que se muestre a continuación de los símbolos // formará parte del comentario:

const numero = 2; // Asignamos el valor 2 a "numero"
const resultado = numero + 4; // Asignamos la suma de "numero" y 4 a "resultado"

Los comentarios en línea se usan para realizar anotaciones acerca de porciones de código pequeñas y muy concretas que generalmente comienzan en la siguiente línea o están situadas justo antes del comentario, en la misma línea. Es el tipo de comentario más común

No es posible delimitar el final de los comentarios en línea, ocupando así el resto de la línea a partir del lugar en el que se definen. En el siguiente ejemplo, la definición del comentario provocará un error de sintaxis, ya que la llave de apertura del bucle for está comentada:

for (let i = 0; i === 4; i++) // bucle que iterará cuatro veces {
  // Este código dará lugar a un error de sintaxis
}

Los comentarios en línea son muy útiles y son un buen modo de explicar el funcionamiento de pequeñas porciones de código. Sin embargo, es mejor no abusar de ellos, ya que pueden dar lugar a un código poco legible.

Comentarios en bloque

Los comentarios en bloque o multilínea se usan para crear anotaciones que explican secciones del código relativamente extensas. Se suelen usar tanto al inicio de los archivos JavaScript como inmediatamente antes de declarar las clases, los métodos o las funciones:

/* Declaración de la función saludar, en la que
usamos el nombre del usuario que pasamos como argumento
para mostrar un saludo por la consola. */

function saludar(usuario) {
  const nombre = usuario;
  console.log('Hola,' + nombre);
}

saludar();

Los comentarios en bloque también se suelen representar con una barra y dos asteriscos como símbolos de apertura. Este tipo de comentario suele usarse para los DocBlocs, que permiten documentar las clases, los métodos y las funciones JavaScript mediante la sintaxis JSDoc:

/**
 * Descripción de la función
 * 
 * @param {string}      nombre          Nombre del usuario
 * @param {string}      apellido        Apellido del usuario
 * @param {number=}     edad            Edad del usuario (opcional)
 * 
 * @returns {Object}
 */
function Person(nombre, apellido, edad = 0) {
  return {nombre, apellido, edad};
}

Al principio, cuando estás aprendiendo JavaScript, seguramente agregues bastantes comentarios explicando la utilidad del código. Con posterioridad, aunque también incluyas comentarios, seguramente tengas una mayor preferencia por los DocBlocs, que siguen un estándar y sirven también para generar documentaciones con diversas herramientas,.

Utilidad de los comentarios

Tanto los comentarios en línea como los comentarios multilínea tienen diversas funcionalidades en JavaScript. En general suelen usarse para explicar el código, aunque también pueden usarse para excluir una porción del código temporalmente.

Los comentarios pueden usarse para explicar lo que hace el código o cómo funciona, tal y como puede verse en el siguiente ejemplo:

// Muestra "Hail to the king, baby!" por la consola
console.log('Hail to the king, baby!');

Cuando redactas un comentario con la intención de explicar el código, debes agregar una sangría que esté al mismo nivel que el código al que hace referencia, tal y como ves en este ejemplo:

// Inicializa una función
function listarContinentes() {
  // Define la variable continentes como un array de cadenas
  const continentes = ['Europa', 'América', 'Asia', 'África', 'Oceanía', 'Antártida'];

  // Muestra el array de continentes por la consola
  console.log(continentes);
}

Los comentarios forman parte del código de la aplicación que desarrollas, por lo que son igual de importantes que el resto del código. Además, es importante que los comentarios se actualicen a medida que modificas el código, ya que un comentario desactualizado o carente de sentido es mucho peor que la ausencia del mismo, ya que podrías confundir a los programadores.

Los comentarios también se usan para excluir una porción del código, evitando así que se ejecute. Esto resulta muy habitual cuando realizas pruebas o depuras el código. Comentar pequeñas porciones del código te ayudará a descubrir errores. Además, también te ayudará a probar diversos modos de solucionar un problema, alternando entre diferentes funciones sin necesidad de usar archivos externos:

// Suma dos números
function suma(n1, n2) {
  return n1 + n2;
}

// Multiplica dos números
function multiplica(n1, n2) {
  return x * y;
}

/* En el siguiente ejemplo comentamos una de las funciones,
evitando así que se ejecute */

// suma(1, 2);
multiplica(2, 5);

Para comentar el código temporalmente puedes valerte tanto de comentarios de una sola línea como de comentarios multilínea. Sin embargo, es importante que solamente uses estos comentarios durante tus pruebas con el objetivo de encontrar errores o excluir o probar ciertas funcionalidades. El código que uses finalmente no debería contener código excluido con comentarios.

Por qué debes usar comentarios

Es importante que tengas en cuenta que seguramente tú u otros desarrolladores revisaréis el código en el futuro. Por ello, es recomendable realizar anotaciones o explicar aquellas porciones de código difíciles de entender.

Si eres un programador con conocimientos avanzados, has de pensar también en aquellos programadores que no están todavía a tu nivel. Un pequeño comentario puede ahorrar mucho tiempo y quebraderos de cabeza. El uso de comentarios, en general, es una buena práctica.

Comentarios en otros lenguajes

Si quieres saber cómo agregar comentarios en otros lenguajes de programación, consulta los siguientes tutoriales:

• Comentarios en HTML: Cómo agregar comentarios en HTML
• Comentarios en CSS: Cómo agregar comentarios en CSS

Esto ha sido todo.

---