Escribir Comentarios en JavaScript

Introducción

En la programación, se sabe que la computadora está leyendo e interpretando el código que escribimos. Sin embargo, es igualmente importante considerar a las personas que estarán leyendo y trabajando con el código. Ya sea que esté trabajando con un equipo o por su cuenta, tendrá que aprender a comentar y estructurar adecuadamente su código para los lectores humanos.

Los comentarios son anotaciones en el código fuente de un programa que son ignoradas por el intérprete y, por lo tanto, no tienen ningún efecto en la salida real del código. Los comentarios pueden ser enormemente útiles para explicar la intención de lo que su código es o debería estar haciendo.

¿Comó desarrollador?, puede ser frustrante investigar el código escrito por alguien que no se ha comentado correctamente y es muy fácil olvidar lo que su propio código significaba cuando ya no está inmerso en el contexto de un programa. Al comentar su código de forma temprana, reforzará los buenos hábitos de programación a lo largo de su carrera para evitar estos problemas más adelante.

Sintaxis del Comentario

Echemos un rápido vistazo a los dos tipos diferentes de sintaxis de comentarios JavaScript.

Los comentarios de una sola línea se escriben con dos barras diagonales ( // ):

// This is a comment

Todos los caracteres inmediatamente después de la sintaxis // hasta que el final de la línea será ignorado por JavaScript.

Los comentarios de bloque , denominados a veces comentarios de línea mutua, se escriben con etiquetas de apertura ( /* ) y etiquetas de cierre ( */ ). Si conoce CSS, ya está familiarizado con los comentarios a nivel de bloque.

/* This is
a comment */

Todo lo que se encuentre entre la etiqueta de apertura y cierre en el bloque de código anterior será ignorado.

Tanto los comentarios de una sola línea como los de varias líneas se escriben encima del código que están designados para explicar, como se demuestra en este "Hello, World!". Por ejemplo:

// Print "Hello, World!" to the console
console.log("Hello, World!");

Al escribir comentarios, suergue al mismo timpo un nivel del código debajo de ellos:

// Initialize a function
function alphabetizeOceans() {
    // Define oceans variable as a list of strings
    const oceans = ["Pacific", "Atlantic", "Indian", "Antarctic", "Arctic"];

    // Print alphabetized array to the console
    console.log(oceans.sort());
}

Tenga en cuenta que los comentarios son tan parte del código como el propio programa. Los comentarios obsoletos pueden ser más perjudiciales que ningún comentario, así que recuerde mantener y actualizar los comentarios regularmente junto con todo lo demás.

Comentarios en Línea

Los comentarios de una sola línea se denominan comentarios en línea cuando aparecen al final de una línea de código.

let x = 99;    // assign numerical value to x
let y = x + 2; // assign the sum of x + 2 to y

Los comentarios en línea se pueden utilizar para anotaciones rápidas en pequeños fragmentos específicos de contenido. Dado que el comentario sólo debe referirse a la línea exacta en la que está escrito, es el tipo de comentario más obvio.

Recuerde que no hay manera de terminar un solo comentario de línea en una línea, así que asegúrese de no poner ningún código después de la sintaxis // , como se ve en el ejemplo siguiente.

for (let i = 0; i === 10; i++) // for loop that runs ten times {
    // Running this code results in a syntax error
}

Aunque los comentarios en línea pueden ser útiles, se deben utilizar con moderación - el código cubierto en una abundancia de comentarios en línea se convertirá rápidamente en sucia y por lo tanto difícil de leer.

Bloquear Comentarios

Los comentarios a nivel de bloque, o comentarios de varias líneas, son anotaciones largas utilizadas para introducir y explicar una sección de código. A menudo, estos tipos de comentarios se colocan en la parte superior de un archivo, o antes de un bloque de código particularmente complicado.

/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */

function greetUser() {
    const name = prompt("What is your name?");
    console.log("Hello ," + name + "! How are you?");
}

greetUser();

También puede ver a veces una versión ligeramente modificada de la sintaxis de comentario de bloque, que comienza con /** e incluye asteriscos en todo el lado izquierdo del bloque de comentario.

/**
 * Initialize constant with an array of strings.
 * Loop through each item in the array and print
 * it to the console.
 */

const seaCreatures = ["Shark", "Fish", "Octopus"];

for (const seaCreature of seaCreatures) {
  console.log(seaCreature);
}

A veces, este tipo de comentario también incluirá detalles sobre el archivo de programación, incluyendo el nombre, la versión y el autor del guión.

Si eres un principiante en JavaScript, puedes escribir tanto como sea necesario para aprender y comprender el código que escribes. A medida que avanza como desarrollador de JavaScript, buscará responder a la intención, o el ¿por qué? detrás del código, en lugar de ¿cómo? o ¿qué? .

Comentar el Código para las Pruebas

Los comentarios también se pueden utilizar para prevenir rápida y fácilmente la ejecución de código para fines de prueba y depuración. Esto se conoce como "commenting out code".

Si hay algún error en algún código que haya escrito, comentar las secciones evitará que se ejecuten y puede ser útil para localizar el origen del problema. También puede usarlo para alternar entre el código para probar diferentes resultados.

// Function to add two numbers
function addTwoNumbers(x, y) {
  let sum = x + y;
  return sum;
}

// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
  let product = x * y;
  return product;
}

/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */

// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9);

Tanto los comentarios de una sola línea como los comentarios de bloque pueden utilizarse para comentar el código, dependiendo del tamaño de la sección que se esté conmutando.

Nota : Comentar el código sólo debe hacerse durante las pruebas. No dejes fragmentos de código comentado en tu guión final.

Al elaborar la lógica de un programa, comentar el código puede resultar útil al determinar dónde están los errores o evaluar las líneas de código que ofrecen la mayor utilidad.

Conclusión

El código JavaScript es interpretado por la computadora, pero siempre será leído por otros programadores, incluyendo su futuro yo. Tomando el tiempo para dejar la anotación apropiada en secciones complicadas del código pagará dividendos en el futuro, haciéndolo más fácil para que usted y los colaboradores entiendan la intención del código que usted ha escrito.