Ir al contenido principal

Comentarios en el código JavaScript

Introducción

El código que escribimos no solo debe ser entendido por los ordenadores, sino también por nosotros mismos y por otros programadores. Cuando desarrollamos software, estamos contando una historia: explicando a la máquina qué hacer y, al mismo tiempo, comunicando a otros seres humanos nuestra intención y razonamiento. Los comentarios son una herramienta fundamental en este proceso de comunicación. Son fragmentos de texto que el intérprete de JavaScript ignora, pero que resultan invaluables para documentar nuestro código, explicar decisiones complejas, o incluso desactivar temporalmente partes de nuestro programa. En este artículo, exploraremos en profundidad los comentarios en JavaScript: su sintaxis, propósito, y las mejores prácticas para utilizarlos de manera efectiva en nuestros proyectos.

Tipos de comentarios en JavaScript

JavaScript ofrece dos formas principales de añadir comentarios a nuestro código:

Comentarios de una línea

Los comentarios de una línea comienzan con dos barras diagonales (//) y continúan hasta el final de la línea. Son ideales para explicaciones breves o notas rápidas.

// Esto es un comentario de una línea
let edad = 25; // También podemos colocar comentarios al final de una instrucción

// Las siguientes líneas calculan el área de un círculo
const PI = 3.14159;
const radio = 5;
const area = PI * radio * radio;

Cualquier texto que siga a las dos barras será ignorado por el intérprete de JavaScript, lo que nos permite escribir explicaciones, notas, o incluso código que no queremos ejecutar temporalmente.

Comentarios multilínea

Los comentarios multilínea (también llamados comentarios de bloque) comienzan con /* y terminan con */. Todo lo que está entre estos delimitadores será ignorado por JavaScript, incluso si se extiende por varias líneas.

/*
Este es un comentario multilínea.
Puede extenderse por varias líneas.
Es ideal para explicaciones más extensas o para documentar
funciones, clases, o secciones completas de código.
*/

function calcularAreaCirculo(radio) {
    /* 
    Esta función calcula el área de un círculo
    Parámetros:
      - radio: El radio del círculo (número)
    Retorna:
      - El área del círculo
    */
    const PI = 3.14159;
    return PI * radio * radio;
}

Los comentarios de bloque son especialmente útiles para documentaciones extensas, para explicar algoritmos complejos, o para "comentar" (desactivar) grandes secciones de código durante la fase de desarrollo o depuración.

Diferencias y cuándo utilizar cada tipo

Aunque ambos tipos de comentarios cumplen la misma función básica (ser ignorados por el intérprete), existen diferencias prácticas en su uso:

Tipo Uso recomendado Ventajas Desventajas
Una línea (//) Comentarios breves, explicaciones junto al código, desactivar temporalmente una línea Simple, no interfiere con la indentación del código No adecuado para textos largos
Multilínea (/* */) Documentación de funciones, explicaciones extensas, desactivar bloques de código Permite estructurar mejor textos largos Puede afectar a la indentación, más verboso para comentarios simples
Situaciones comunes para cada tipo de comentario:

Comentarios de una línea (//):

  • Explicaciones rápidas de variables o expresiones
  • Notas TODO o FIXME para revisión posterior
  • Desactivar temporalmente una línea mientras probamos alternativas
  • Añadir separadores o marcadores en el código

Comentarios multilínea (/* */):

  • Documentación formal de funciones, métodos o clases
  • Explicación detallada de algoritmos complejos
  • Cabeceras de archivos (información sobre autor, licencia, etc.)
  • Desactivar temporalmente grandes bloques de código

Propósito de los comentarios

Los comentarios pueden servir para diversos propósitos fundamentales en nuestro código:

1. Documentar el código

Uno de los usos más importantes de los comentarios es documentar qué hace nuestro código y por qué lo hace de esa manera. Esta documentación es invaluable tanto para otros desarrolladores como para nosotros mismos cuando revisamos código antiguo.

/**
 * Valida un código postal español.
 * En España, los códigos postales constan de 5 dígitos,
 * donde los dos primeros identifican la provincia.
 * 
 * @param {string} codigoPostal - El código postal a validar
 * @returns {boolean} - Verdadero si es válido, falso en caso contrario
 */
function validarCodigoPostalEspanol(codigoPostal) {
    // Verificamos que sea una cadena de exactamente 5 caracteres numéricos
    const patron = /^\d{5}$/;
    return patron.test(codigoPostal);
}

En este ejemplo, el comentario explica no solo qué hace la función, sino también proporciona contexto sobre los códigos postales en España y detalles sobre los parámetros y el valor de retorno.

2. Explicar decisiones complejas

Muchas veces, el "por qué" de una decisión de código no es evidente a partir del código mismo. Los comentarios son ideales para explicar razonamientos complejos o soluciones no obvias.

function optimizarConsulta(datos) {
    // Usamos Map en lugar de un objeto convencional porque necesitamos
    // mantener el orden de inserción y tener un rendimiento O(1) en búsquedas
    // con un gran volumen de entradas (>10000 elementos)
    const cache = new Map();
    
    // Precomputamos los resultados para las consultas más frecuentes
    for (let consulta of consultasFrecuentes) {
        // Aplicamos memoización para evitar cálculos repetidos
        if (!cache.has(consulta.id)) {
            cache.set(consulta.id, calcularResultado(consulta, datos));
        }
    }
    
    return cache;
}

Aquí, los comentarios explican el razonamiento detrás del uso de Map en lugar de un objeto simple, y el motivo para implementar memoización, lo cual podría no ser evidente solo mirando el código.

3. Marcar tareas pendientes (TODOs)

Es común utilizar comentarios para marcar partes del código que necesitan revisión, mejora o implementación futura.

function procesarPago(pedido) {
    // TODO: Implementar integración con la pasarela de pago
    console.log("Procesando pago para el pedido:", pedido.id);
    
    // FIXME: La validación de tarjeta no funciona con tarjetas American Express
    validarInformacionPago(pedido.metodoPago);
    
    // TODO (Sprint 23): Añadir soporte para criptomonedas
    return true; // Simulamos éxito por ahora
}

Este tipo de comentarios es especialmente útil en entornos de desarrollo en equipo, donde diferentes personas pueden estar trabajando en distintas partes del código.

4. Desactivar código temporalmente

Durante el desarrollo y la depuración, a menudo necesitamos desactivar temporalmente ciertas partes del código sin eliminarlas por completo. Los comentarios son perfectos para esto.

function calcularTotal(productos) {
    let total = 0;
    
    for (let producto of productos) {
        total += producto.precio * producto.cantidad;
        
        // Descomentar para aplicar descuento por volumen
        /*
        if (producto.cantidad > 10) {
            total -= producto.precio * producto.cantidad * 0.05;
        }
        */
    }
    
    // Versión anterior del cálculo de impuestos
    // total = total * 1.21; // Añadir IVA del 21%
    
    // Nueva versión con función separada
    total = aplicarImpuestos(total);
    
    return total;
}

Este uso de los comentarios es especialmente útil durante la fase de pruebas o cuando estamos implementando nuevas características sin querer perder el código anterior.

Buenas prácticas para documentar código

Escribir buenos comentarios es un arte que se perfecciona con la práctica. Aquí hay algunas recomendaciones para mejorar la documentación de tu código:

Claridad y concisión

Los buenos comentarios son claros y concisos. Deben proporcionar información valiosa sin redundancias ni complejidad innecesaria.

// Malo: Incrementamos el contador i en uno cada iteración
for (let i = 0; i < productos.length; i++) { ... }

// Malo: Esta función calcula el total sumando los productos
function calcularTotal(productos) { ... }

// Bueno: Aplicamos recargo del 5% a pedidos internacionales por costes de envío
if (pedido.esInternacional) {
    total *= 1.05;
}

Los dos primeros ejemplos son malos porque simplemente repiten lo que ya es obvio en el código. El tercer ejemplo es bueno porque explica el motivo detrás de la acción, lo cual no es evidente mirando solo el código.

Comentar el "por qué", no el "qué"

El código ya dice "qué" hace. Los comentarios deberían explicar "por qué" lo hace, especialmente cuando la razón no es obvia.

// Malo: Multiplicamos el precio por 0.8
precioFinal = precioOriginal * 0.8;

// Bueno: Aplicamos descuento del 20% por promoción de verano
precioFinal = precioOriginal * 0.8;

El primer comentario solo repite lo que ya vemos en el código. El segundo explica la razón detrás de la operación, añadiendo valor real.

Estilo y consistencia

Mantén un estilo consistente en tus comentarios a lo largo de todo el proyecto:

  • Usa mayúsculas y puntuación adecuadas
  • Mantén un tono profesional
  • Sé consistente con los términos técnicos
  • Si trabajas en equipo, sigue las convenciones establecidas
// Inconsistente: aqui calculamos el total con iva
// Inconsistente: AQUI SUMAMOS LOS PRODUCTOS DEL CARRITO!!
// Inconsistente: esta fn aplica el descuento xq es martes

// Consistente: Calculamos el precio con IVA incluido (21%)
// Consistente: Aplicamos descuento del 15% por ser martes

La consistencia hace que el código sea más profesional y facilita su lectura y mantenimiento.

Evitar comentarios obsoletos o redundantes

Los comentarios que ya no reflejan lo que hace el código son peores que la ausencia de comentarios, porque pueden llevar a confusión.

// Calculamos el precio con IVA del 16%
precioConIVA = precio * 1.21; // Nota: el IVA actual es 21%

// Enviamos correo de confirmación
// NOTA: Desactivado temporalmente hasta solucionar el bug #1234
enviarCorreoConfirmacion(usuario.email);

En estos ejemplos, los comentarios contienen información contradictoria o ya no reflejan la realidad del código. Es importante mantener los comentarios actualizados cuando el código cambia.

JSDoc y otras convenciones de documentación

Para proyectos más grandes o equipos de desarrollo, es recomendable utilizar convenciones formales de documentación. La más popular en JavaScript es JSDoc.

Introducción a JSDoc

JSDoc es un sistema de documentación para JavaScript que utiliza comentarios con una sintaxis específica. Permite generar documentación HTML automáticamente y proporciona información de tipos y descripciones a los IDEs.

/**
 * Calcula el importe total de un pedido, incluyendo impuestos y descuentos.
 *
 * @param {Object} pedido - El pedido a procesar
 * @param {Array} pedido.productos - Array de productos en el pedido
 * @param {boolean} pedido.envioPrioritario - Si el envío es prioritario
 * @param {string} pedido.codigoDescuento - Código de descuento (opcional)
 * @param {number} [porcentajeImpuesto=21] - Porcentaje de impuesto a aplicar
 * @returns {number} El importe total del pedido
 * @throws {Error} Si el pedido no contiene productos
 * @example
 * const pedido = {
 *   productos: [{id: 1, precio: 29.99, cantidad: 2}],
 *   envioPrioritario: false,
 *   codigoDescuento: "VERANO2023"
 * };
 * const total = calcularImportePedido(pedido);
 * // Devuelve: 72.57 (con IVA y descuento aplicados)
 */
function calcularImportePedido(pedido, porcentajeImpuesto = 21) {
    if (!pedido.productos || pedido.productos.length === 0) {
        throw new Error("El pedido debe contener al menos un producto");
    }
    
    // Cálculo del importe base
    let total = pedido.productos.reduce((suma, producto) => {
        return suma + producto.precio * producto.cantidad;
    }, 0);
    
    // Aplicar descuentos si hay código
    if (pedido.codigoDescuento) {
        const descuento = obtenerDescuento(pedido.codigoDescuento);
        total -= total * (descuento / 100);
    }
    
    // Añadir coste de envío prioritario si corresponde
    if (pedido.envioPrioritario) {
        total += 9.99;
    }
    
    // Aplicar impuestos
    total += total * (porcentajeImpuesto / 100);
    
    return Number(total.toFixed(2)); // Redondeamos a 2 decimales
}

Este ejemplo muestra cómo documentar una función utilizando JSDoc. Observa cómo incluye:

  • Una descripción general de la función
  • Documentación de parámetros con tipos y descripciones
  • Información sobre el valor de retorno
  • Documentación de posibles excepciones
  • Un ejemplo de uso

Etiquetas JSDoc comunes

JSDoc utiliza "etiquetas" que comienzan con @ para estructurar la documentación:

Etiqueta Descripción Ejemplo
@param Documenta un parámetro @param {string} nombre - Nombre del usuario
@returns Documenta el valor de retorno @returns {boolean} True si la operación tuvo éxito
@throws Documenta errores que puede lanzar @throws {Error} Si el archivo no existe
@example Proporciona un ejemplo de uso @example calcularArea(5, 10)
@deprecated Indica que una función está obsoleta @deprecated Usar nuevaFuncion() en su lugar
@since Versión en la que se introdujo @since 1.2.0
@see Referencias relacionadas @see calcularImpuestos
@todo Tareas pendientes @todo Implementar validación de entrada

Beneficios de usar JSDoc

Utilizar JSDoc tiene múltiples ventajas:

  1. Documentación generada automáticamente: Puedes usar herramientas como jsdoc para generar sitios de documentación HTML a partir de tus comentarios.

  2. Mejora la experiencia en editores: Editores como VS Code utilizan los comentarios JSDoc para proporcionar autocompletado, sugerencias de tipos y ayuda contextual.

  3. Facilita la comprensión del código: Otros desarrolladores (o tú mismo en el futuro) pueden entender rápidamente cómo usar tus funciones.

  4. Integración con TypeScript: JSDoc puede proporcionar verificación de tipos sin necesidad de migrar completamente a TypeScript.

// VS Code mostrará información de tipos y descripción al usar esta función
/**
 * @param {string} nombre - Nombre del usuario
 * @param {number} edad - Edad del usuario
 * @returns {Object} Objeto de usuario formateado
 */
function crearUsuario(nombre, edad) {
    return {
        nombre,
        edad,
        fechaCreacion: new Date()
    };
}

// Al escribir:
crearUsuario("Ana", ); // El editor sugerirá que el segundo parámetro debe ser un número

Otras convenciones de documentación

Además de JSDoc, existen otras convenciones que puedes encontrar en proyectos JavaScript:

YUIDoc

Similar a JSDoc, fue popular en proyectos que utilizaban YUI (Yahoo! User Interface Library):

/**
 * Calcula el área de un rectángulo.
 *
 * @method calcularArea
 * @param {Number} ancho El ancho del rectángulo
 * @param {Number} alto El alto del rectángulo
 * @return {Number} El área calculada
 */
Documentación de Google Closure

Utilizada en proyectos que usan Google Closure Compiler:

/**
 * Calcula el área de un rectángulo.
 *
 * @param {number} ancho El ancho del rectángulo.
 * @param {number} alto El alto del rectángulo.
 * @return {number} El área calculada.
 */
Natural Docs

Un estilo más natural, menos formal:

/*
 Función: calcularArea
 
 Calcula el área de un rectángulo multiplicando ancho por alto.
 
 Parámetros:
   ancho - El ancho del rectángulo en unidades.
   alto - El alto del rectángulo en las mismas unidades.
 
 Devuelve:
   El área calculada en unidades cuadradas.
*/

Resumen

En este artículo hemos explorado en profundidad los comentarios en JavaScript: su sintaxis, propósito, y las mejores prácticas para utilizarlos de manera efectiva en nuestros proyectos. Hemos visto cómo los comentarios no solo sirven para documentar qué hace nuestro código, sino también para explicar decisiones, marcar tareas pendientes, y proporcionar contexto importante que no es evidente a partir del código mismo.

Recuerda estos puntos clave:

  • Los comentarios de una línea (//) son ideales para explicaciones breves, mientras que los comentarios multilínea (/* */) son mejores para documentación extensa.
  • Los buenos comentarios explican el "por qué" detrás del
Volver arriba