Cómo escribir comentarios

En esta lección aprenderás a escribir comentarios en JavaScript para dejar un código fácil de entender incluso cuando vuelvas a él más adelante. Está pensada para quien busca «cómo comentar código en JavaScript».

Un comentario es una «nota para personas» que no afecta en nada a la ejecución del programa. Se escriben para que tú (u otra persona) entendáis mejor el código después. // abre un comentario de una línea, y /* */ envuelve uno de varias líneas. El código escrito dentro de un comentario no se ejecuta, así que también se usan mucho para desactivar código temporalmente (comentarlo).

El código de ejemplo añade la explicación de una variable con un comentario de una línea y una explicación más larga con uno de varias. Poner una nota corta a la derecha o encima de una variable —como // precio del artículo (euros)— es un estilo muy usado en proyectos reales. Los comentarios pueden ir en inglés o en el idioma que prefiera tu equipo; la regla básica es seguir la convención del equipo.

Un tropiezo habitual al empezar es escribir tantos comentarios que el código acaba siendo más difícil de leer. «Qué está pasando» suele entenderse leyendo el propio código, así que es más eficaz reservar los comentarios para «por qué hace falta este proceso». A la inversa, el código complejo sí merece comentarios de forma proactiva: calidad antes que cantidad.

En el desarrollo real, que existan o no comentarios marca una diferencia enorme al trabajar en equipo. Cuando tú o un compañero volváis al código meses después, un comentario que transmita la intención original acelera muchísimo las correcciones y la investigación de fallos. Escribir buenos comentarios se considera parte de la competencia profesional.

Muchos editores tienen un atajo de teclado para comentar de golpe el rango seleccionado, muy cómodo cuando quieres desactivar código temporalmente para probar algo. Merece la pena usarlo con frecuencia.

Existe un formato especial de comentario llamado JSDoc (se escribe como /** ... */, describiendo la función, sus argumentos y su valor de retorno) con el que muchos editores muestran automáticamente la descripción de esa función, lo que mejora la eficiencia del trabajo en equipo.