Comentarios en YAML: cómo comentar y desactivar líneas
Comentarios en YAML
Comentarios en YAML: sintaxis, reglas en línea y alternativas al bloque | We.Inc
Cómo comentar en YAML: la sintaxis #, la regla del espacio en los comentarios en línea, por qué no hay comentarios de bloque y una herramienta que comenta o restaura muchas líneas a la vez.
Un comentario de YAML empieza con una almohadilla (#) y llega hasta el final de la línea. Puede ir en su propia línea o después de un valor, siempre que haya un espacio en blanco que lo separe del valor. YAML no tiene sintaxis de comentario de bloque, así que comentar varias líneas implica poner # al principio de cada una.
Dónde # inicia un comentario en YAML y dónde no
Línea
¿El # es un comentario?
Por qué
Sí
Empieza la línea
port: 5432 # default
Sí
Hay un espacio antes del #
url: https://x.example/#top
No
No hay espacio antes del #, así que forma parte del valor
color: "#4F98FB"
No
Está dentro de una cadena entre comillas
tag: #blue
Sí
El valor queda vacío (null) y el resto es un comentario
Los comentarios son el principal motivo por el que los equipos eligen YAML en lugar de JSON para la configuración, pero es fácil tropezar con sus reglas. Pega un archivo en la herramienta de abajo para comentar o restaurar un rango de líneas, y luego revisa la referencia para ver los casos en que un # pasa sin avisar a formar parte de tus datos.
Pega tu YAML en el cuadro o edita el ejemplo.
Introduce los números de la primera y la última línea que quieres cambiar.
Pulsa Comentar para añadir # después de la indentación de cada línea, o Descomentar para quitarlo.
Copia el resultado de vuelta a tu archivo. Las líneas en blanco del rango no se tocan.
Mantén el # alineado con el código que desactiva. Las líneas comentadas con la misma indentación son mucho más fáciles de restaurar después.
Pon un espacio después del # en tus propias notas. No es obligatorio, pero hace fácil distinguir el código comentado de las observaciones.
Pon entre comillas cualquier valor que contenga un # que quieras conservar, como los colores hexadecimales, para que una edición posterior no lo convierta en comentario.
Recuerda que la mayoría de las librerías descartan los comentarios cuando cargan un archivo y lo vuelven a guardar. No guardes nada importante solo en un comentario que las herramientas reescriben.
Preguntas frecuentes
¿YAML tiene comentarios multilínea o de bloque?
No. La especificación solo define comentarios de línea que empiezan con #. Para desactivar un bloque, pon # delante de cada línea. La mayoría de los editores lo hacen para una selección con un solo atajo, y la herramienta de esta página lo hace para cualquier rango de líneas.
¿Por qué mi comentario pasó a formar parte del valor?
Un # solo inicia un comentario cuando lo precede un espacio en blanco. En url: https://site.example/#faq el # va detrás de una barra, así que se queda dentro de la cadena. Añade un espacio antes del # si querías un comentario.
¿Se conservan los comentarios al convertir YAML a JSON?
No. Los comentarios son un detalle de presentación, no datos, y JSON no tiene dónde ponerlos. El RFC 9512 señala que los comentarios se descartan cuando YAML se serializa como JSON.
¿Puedo comentar dentro de un block scalar?
No. Dentro de un bloque | o >, una línea que empieza con # es texto normal y pasa a formar parte de la cadena. Los comentarios solo funcionan fuera de las líneas de contenido del bloque.
¿Cuál es el atajo para comentar YAML en un editor?
Depende del editor, no de YAML. En Visual Studio Code el comando Toggle Line Comment es Ctrl+/ en Windows y Linux y Cmd+/ en macOS; otros editores definen sus propias teclas.
Comentarios en línea y la regla del espacio
La especificación de YAML dice que los comentarios deben separarse de los demás tokens con espacio en blanco. Esa única regla explica casi todas las sorpresas: un # pegado al texto anterior es dato, y un # después de un espacio es el inicio de una nota.
Aquí un tabulador también cuenta como espacio en blanco, pero como los tabuladores no se permiten en la indentación, es más sencillo usar espacios en todas partes.
Documentar bien un archivo de configuración
Escribe comentarios que digan por qué se fija un valor, no lo que ya dice el nombre de la clave. Una línea como # 5 reintentos porque la API de pagos agota el tiempo bajo carga le ahorra a la siguiente persona una búsqueda en el historial.
Pon un breve comentario de cabecera al principio que diga qué programa lee el archivo y dónde están documentadas todas sus opciones.
Patrones de comentario que usarás
Comentarios de línea completa y en línea
Un comentario de línea completa explica una sección; un comentario en línea necesita al menos un espacio antes del #.
Desactivar un bloque temporalmente
Cada línea del servicio desactivado lleva su propio #, mantenido en la indentación original para poder restaurarlo limpiamente.
Comenta líneas de YAML
Pega YAML, elige un rango de líneas y cambia esas líneas entre activas y comentadas. La indentación se conserva, así que la estructura sigue siendo fácil de leer.