Documentación en JavaScript: cómo escribir código que habla por sí mismo

Por qué la documentación no es una obligación aburrida, sino un superpoder del desarrollador

Imagina: abres un proyecto JavaScript ajeno (o el tuyo propio de hace tres meses). Los archivos están llenos de funciones flecha, async/await y desestructuración. Pero ¿por qué esta función se llama transformData? ¿Qué recibe? Y lo más importante: ¿para qué sirve si al lado hay un processArray?

Si alguna vez te has sorprendido pensando: «No recuerdo qué está pasando aquí», este artículo es para ti. La documentación en JavaScript no se trata de párrafos aburridos. Se trata de respeto hacia tu yo futuro y tus colegas. Se trata de velocidad al integrarse en un proyecto y de reducir la cantidad de errores. En este artículo, analizaremos las mejores prácticas para documentar código JS: desde JSDoc hasta la generación de documentación completa.

Documentación de código JavaScript: la filosofía del «código que habla»

Antes de escribir comentarios, es importante entender: el mejor comentario es el que no hace falta. El código ideal debería explicarse por sí mismo. ¿Cómo lograrlo?

Nombres de variables y funciones

Ejemplo malo:

// Mal\nconst x = 10; // ¿qué es x?\nfunction d(a, b) { return a * b; } // ¿qué hace d?\n

Ejemplo bueno:

// Bien\nconst MAX_RETRY_COUNT = 10;\nfunction calculateDiscountedPrice(price, discountPercent) {\n  return price * (1 - discountPercent / 100);\n}\n

Usa nombres completos y con significado. Nombra las funciones con verbos (getUser, validateEmail) y las variables con sustantivos (userList, isActive). Esta es la base del código autodocumentado.

Cuándo sí son necesarios los comentarios

\n
• Lógica de negocio compleja: por ejemplo, un cálculo de impuestos con una fórmula poco evidente.
\n
• Un hack o solución temporal: márcalo con TODO o FIXME.
\n
• Por qué se eligió ese enfoque: había alternativas, pero esta es la óptima en velocidad.
\n
• Descripción de una API pública: para que otros desarrolladores sepan cómo llamar a tu función.
\n

JSDoc: el estándar de documentación en JavaScript

JSDoc es una sintaxis para escribir documentación directamente en el código, que es entendida por los editores (VS Code, WebStorm) y las herramientas de generación. Es un must-have para cualquier proyecto serio.

Anotación básica de una función

/**\n * Calcula el costo total del pedido aplicando descuento e impuesto.\n * @param {number} price - Precio base del producto.\n * @param {number} discount - Descuento en porcentaje (0-100).\n * @param {number} taxRate - Tasa de impuesto en porcentaje (0-100).\n * @returns {number} Costo total.\n */\nfunction calculateTotal(price, discount, taxRate) {\n  const discountedPrice = price * (1 - discount / 100);\n  return discountedPrice * (1 + taxRate / 100);\n}\n

Ahora, al pasar el cursor sobre la función calculateTotal en el editor, verás su descripción, parámetros y valor de retorno. ¡Magia!

Anotaciones para objetos y tipos

/**\n * @typedef {Object} User\n * @property {number} id - Identificador único.\n * @property {string} name - Nombre del usuario.\n * @property {boolean} isActive - Si la cuenta está activa.\n */\n\n/**\n * Obtiene la lista de usuarios activos.\n * @param {User[]} users - Array de usuarios.\n * @returns {User[]} Array filtrado.\n */\nfunction getActiveUsers(users) {\n  return users.filter(user => user.isActive);\n}\n

El uso de @typedef permite crear tipos personalizados, lo que hace que el código sea legible y seguro. Esto es especialmente útil en proyectos sin TypeScript.

Documentación de funciones asíncronas

/**\n * Carga los datos del usuario desde el servidor.\n * @async\n * @param {number} userId - ID del usuario.\n * @returns {Prom