Dos tipos de comentarios
En JavaScript existen dos formas de escribir comentarios. El comentario de una línea empieza con // y abarca hasta el final de la línea:
Un comentario de bloque empieza con /* y termina en el siguiente */. Puede ocupar todas las líneas que necesites:
Ambas formas son completamente ignoradas por el motor de JavaScript. Existen para las personas: para ti, para tu equipo y para ese "tú del futuro" que leerá este código dentro de seis meses.
Comentario de una línea en JavaScript
// es el que vas a usar más. Todo lo que aparezca después de // en esa misma línea se considera comentario; a partir de la siguiente línea, vuelves a estar escribiendo código normal:
Los comentarios al final de una línea (después de una instrucción) están bien para notas cortas. Si la nota crece tanto que se parte en varias líneas, mejor muévela a una línea propia encima del código — los comentarios largos al final se cortan en muchos editores y la gente termina ignorándolos.
Comentarios de bloque en JavaScript
Vale la pena recurrir a /* */ en dos situaciones: cuando el comentario ocupa más de una línea, o cuando necesitas colocarlo en medio de una expresión.
Un detalle que pilla desprevenido a mucha gente: los comentarios de bloque no se anidan. El primer */ cierra el comentario, aunque tú creyeras que seguías dentro de otro bloque más externo:
/* outer /* inner */ still outer */
// SyntaxError — the first */ closed the block,
// and "still outer */" is now invalid code.
Si necesitas comentar código que ya contiene /* */, usa // en cada línea.
Comentar código en JavaScript
Cuando estás depurando, es muy común querer desactivar unas líneas de forma temporal. Las dos formas de comentario te sirven:
Todo editor tiene un atajo para esto: Ctrl+/ en Windows/Linux y Cmd+/ en Mac alternan // en las líneas seleccionadas. Apréndelo una vez y lo vas a usar todos los días.
El código comentado está pensado para ser temporal. No subas al repo cementerios de código muerto con un // versión vieja, por si acaso encima. Para eso está el control de versiones: él se acuerda del código antiguo por ti. Bórralo.
Comenta el porqué, no el qué
Esta es la regla de oro que distingue un comentario útil del puro ruido. El código ya muestra qué hace. Un buen comentario explica por qué lo hace.
Ruido:
Esos comentarios no le aportan nada al lector que el código no diga ya por sí solo. Compara:
Ambos comentarios apuntan a algo que nadie podría deducir solo leyendo el código: una restricción externa, un comportamiento raro documentado. Ese es el listón. Si al quitar el comentario nadie se queda con dudas, es que ese comentario no aportaba nada.
JSDoc: comentarios que las herramientas entienden
JSDoc es una convención para escribir comentarios de bloque que describen funciones de forma estructurada. Los editores y los verificadores de tipos los leen y, a cambio, te ofrecen mejor autocompletado y documentación al pasar el cursor:
El /** (dos asteriscos) es lo que marca el comentario como JSDoc en lugar de un comentario de bloque normal. No hace falta poner JSDoc en cada función: tiene más sentido usarlo en APIs públicas, utilidades compartidas y en cualquier sitio donde los tipos no queden claros con solo leer el código.
Algunos hábitos que vale la pena mantener
- Deja los comentarios pegados al código que describen. Un comentario que está diez líneas más arriba del código relevante termina desincronizándose conforme el código cambia.
- Actualiza los comentarios cuando modifiques el código. Un comentario desactualizado es peor que no tener ninguno: le miente al siguiente que lea el código.
- Mejor un buen nombre que muchos comentarios.
const d = 86400000;necesita un comentario.const MILLISECONDS_PER_DAY = 86_400_000;no. - Marca los pendientes con
TODO:oFIXME:. La mayoría de editores los resalta y son muy fáciles de buscar con grep después.
Una aclaración sobre los comentarios en HTML y JavaScript
Si escribes JavaScript dentro de un archivo HTML, cuidado con no mezclar los dos estilos de comentarios. HTML utiliza <!-- -->, mientras que JavaScript usa // y /* */. Dentro de una etiqueta <script> solo funcionan las formas de JavaScript:
<script>
// Correcto — comentario de JS dentro de <script>
/* También correcto */
<!-- Mal — esto es un comentario HTML y romperá tu JS -->
console.log("hola");
</script>
Los navegadores, por motivos históricos, toleraban <!-- --> dentro de los scripts para dar soporte a navegadores antiguos, pero hoy considéralo algo roto y sigue adelante.
Lo que viene: declarar variables
Ahora que sabes anotar tu código, toca empezar a escribirlo. JavaScript ofrece tres formas de declarar una variable — let, const y var — y elegir la correcta es la primera decisión real que tomarás en cada línea. Eso lo vemos a continuación.
Preguntas frecuentes
¿Cómo se escribe un comentario en JavaScript?
Con // haces un comentario de una sola línea: todo lo que venga después en esa línea se ignora. Con /* ... */ creas un comentario de bloque que puede ocupar varias líneas. Ambas sintaxis funcionan en cualquier archivo .js y también dentro de etiquetas <script> en HTML.
¿Cuál es la diferencia entre // y /* */ en JavaScript?
// llega hasta el final de la línea actual y ahí termina. /* */ empieza en /* y se cierra en el siguiente */, así que puedes abarcar varias líneas o meterlo en mitad de una expresión. Usa // para notas cortas y /* */ cuando necesites varias líneas o quieras anotar parte de una expresión.
¿Cómo comento un bloque de código en JavaScript?
Lo envuelves en /* */ o pones // al inicio de cada línea. La mayoría de editores tienen un atajo: Ctrl+/ (Cmd+/ en Mac) activa o desactiva los // en las líneas seleccionadas. Evita anidar /* */ dentro de otro /* */, porque el primer */ cierra el comentario exterior y te saltará un error de sintaxis.
¿Cuándo conviene escribir un comentario?
Comenta el porqué, no el qué. Si el código hace algo que no se entiende a simple vista —un apaño, una regla de negocio, un truco de rendimiento— explica el motivo. No narres lo que ya se lee en el propio código: una variable o función con buen nombre elimina la necesidad de la mayoría de los comentarios.
