Comentarios y Documentación
En JavaScript, los comentarios y la documentación cumplen un papel esencial para crear proyectos claros, mantenibles y colaborativos. Imagina que estás construyendo una casa: los ladrillos son el código que hace que todo funcione, pero los planos y notas escritas son los comentarios, que permiten a otros (o a ti mismo en el futuro) comprender la intención detrás de cada parte. Sin ellos, la casa puede terminar siendo confusa y difícil de modificar.
En un sitio de portafolio, los comentarios ayudan a marcar qué sección del código corresponde a la galería de proyectos. En un blog, sirven para explicar cómo se cargan los artículos. En un e-commerce, permiten entender qué funciones procesan el carrito de compras. En un sitio de noticias, señalan cómo se actualizan los titulares. En una red social, detallan la lógica de interacción, como dar "me gusta" o compartir publicaciones.
En este tutorial aprenderás cómo escribir comentarios efectivos, cómo documentar funciones para que sean reutilizables y fáciles de mantener, y cuáles son las mejores prácticas que todo programador intermedio debe aplicar. También descubrirás errores comunes que debes evitar y cómo un buen hábito de documentación se conecta con otras áreas del desarrollo web. Al final, tendrás una base sólida para que tu código sea tan claro como una biblioteca bien organizada, donde cada libro está en su lugar con etiquetas precisas.
Ejemplo Básico
javascript// This function calculates the square of a number
function square(num) {
return num * num; // Multiply number by itself
}
console.log(square(4)); // Expected output: 16En este ejemplo, vemos cómo los comentarios explican la intención detrás del código. La primera línea con // es un comentario de una sola línea. Su función es describir qué hace la función square: calcular el cuadrado de un número. Este tipo de explicación es vital porque, aunque el código es sencillo, un lector nuevo podría tardar en comprenderlo si no tiene contexto.
Luego, dentro de la función, encontramos otro comentario: // Multiply number by itself. Aquí, el comentario explica paso a paso lo que ocurre en la operación num * num. Aunque la multiplicación sea evidente, este estilo de documentación es útil en situaciones más complejas, donde la lógica no es tan intuitiva.
Finalmente, al ejecutar console.log(square(4)); añadimos un comentario que indica el resultado esperado. Esto actúa como una verificación rápida para otros desarrolladores y para ti mismo en el futuro.
En proyectos como un blog o una tienda en línea, este enfoque ayuda a identificar qué parte del código genera una acción específica (por ejemplo, calcular descuentos en un carrito o mostrar el número de comentarios en un artículo). Los comentarios actúan como señales que guían al lector, evitando confusión y permitiendo colaborar con mayor fluidez. Un principiante podría preguntarse: “¿Debo comentar cada línea?”. La respuesta es no: lo importante es documentar la intención y las partes menos obvias, no lo evidente.
Ejemplo Práctico
javascript// Function to calculate total price with discount in an e-commerce
function calculateTotalPrice(items, discount) {
// Sum prices of all items
let subtotal = items.reduce((acc, item) => acc + item.price, 0);
// Apply discount percentage
let total = subtotal - (subtotal * discount);
return total; // Final price after discount
}
// Example usage
let cart = \[{price: 20}, {price: 30}, {price: 50}];
console.log(calculateTotalPrice(cart, 0.1)); // Expected output: 90Al avanzar hacia un ejemplo más práctico, observamos cómo los comentarios se vuelven cruciales en escenarios reales como un e-commerce. Aquí, la función calculateTotalPrice recibe una lista de productos y un descuento.
El primer comentario explica que se suman los precios de todos los elementos. La expresión con reduce puede ser confusa para quienes no están acostumbrados, por eso el comentario aclara el propósito: calcular el subtotal.
El segundo comentario aclara la aplicación del descuento, que se resta del subtotal multiplicado por el porcentaje. Finalmente, antes de devolver el valor, un comentario explica que el resultado es el precio final después del descuento.
También incluimos un comentario en el uso del ejemplo para mostrar el resultado esperado. En una tienda en línea, esta función podría usarse al momento de pagar, y los comentarios ayudarían a otros desarrolladores a comprender la lógica sin necesidad de adivinar.
Esto mismo se aplica en proyectos de noticias (para calcular número de vistas), portafolios (para mostrar logros con porcentajes) o redes sociales (para ajustar métricas). Sin documentación clara, modificar este código en el futuro sería como intentar reorganizar una biblioteca sin etiquetas: posible, pero lento y propenso a errores.
Las mejores prácticas en comentarios y documentación se centran en claridad, relevancia y eficiencia. Primero, utiliza una sintaxis moderna y estandarizada, como comentarios de una sola línea // para notas rápidas y bloques /* ... */ para explicaciones más largas. Segundo, incluye documentación en funciones públicas para facilitar la colaboración. Tercero, actualiza los comentarios al mismo tiempo que actualizas el código: un comentario desactualizado puede confundir más que no tener ninguno. Cuarto, aprovecha herramientas como JSDoc para crear documentación estructurada y profesional.
Los errores comunes incluyen comentar lo obvio (por ejemplo, // add 1 to i en un i++), olvidar eliminar comentarios innecesarios, escribir en un lenguaje poco claro, o usar comentarios como “recordatorios” que nunca se actualizan. Otro error es abusar de los comentarios en lugar de mejorar la legibilidad del propio código con nombres descriptivos en funciones y variables.
Un consejo de depuración es utilizar comentarios temporales para aislar partes de código, explicando qué estás probando. Esto evita perder el hilo cuando revises el proyecto después de varias horas.
En la práctica, escribe comentarios pensando en otra persona que leerá tu código como si fuera una carta: claros, cortos y con toda la información necesaria para comprender el mensaje.
📊 Referencia Rápida
| Property/Method | Description | Example |
|---|---|---|
| // | Comentario de una sola línea | // Esto muestra un mensaje |
| /* ... */ | Comentario de múltiples líneas | /* Explica varias líneas de código */ |
| / ... */ | Comentario estilo JSDoc para documentación | / Función que calcula total */ |
| JSDoc @param | Describe parámetros de función | @param {number} precio - precio del producto |
| JSDoc @return | Describe el valor de retorno | @return {number} total con descuento |
En resumen, los comentarios y la documentación no son simples adornos, sino herramientas fundamentales para que el código sea claro y mantenible. Aprendiste que los comentarios guían a otros desarrolladores (y a ti mismo en el futuro), que sirven para proyectos de todo tipo —desde blogs hasta tiendas en línea— y que deben mantenerse actualizados y relevantes.
Este conocimiento se conecta directamente con la manipulación del DOM en HTML, donde es útil documentar qué elementos se modifican y por qué, así como con la comunicación con el backend, donde los comentarios ayudan a describir qué datos se envían o reciben.
Como próximos pasos, te recomiendo estudiar más sobre JSDoc, estándares de documentación de proyectos y cómo aplicar comentarios al trabajar con APIs. También es útil explorar la integración con control de versiones (como Git), donde los comentarios de código se complementan con mensajes claros en los commits.
El consejo práctico más importante: escribe comentarios como si fueran señales en una biblioteca. No necesitas explicar cada estante, pero sí poner etiquetas en las secciones importantes para que cualquiera encuentre rápidamente lo que busca.
🧠 Pon a Prueba tu Conocimiento
Prueba tu Conocimiento
Pon a prueba tu comprensión de este tema con preguntas prácticas.
📝 Instrucciones
- Lee cada pregunta cuidadosamente
- Selecciona la mejor respuesta para cada pregunta
- Puedes repetir el quiz tantas veces como quieras
- Tu progreso se mostrará en la parte superior