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.

    Etiquetas:

    Deja una respuesta

    Tu direcci贸n de correo electr贸nico no ser谩 publicada. Los campos obligatorios est谩n marcados con *