XML tiene exactamente una sintaxis de comentario: el par de delimitadores <!-- -->. A diferencia de YAML o Python, no hay forma abreviada, ni atajo a nivel de línea, ni forma alternativa. Lo que XML ofrece es flexibilidad — el mismo delimitador sirve para notas de una línea, bloques de documentación de varios párrafos y desactivar temporalmente secciones enteras de marcado. Esta guía cubre la sintaxis completa, cada ubicación donde los comentarios XML están prohibidos, la restricción del doble guion que confunde a la mayoría de desarrolladores y las herramientas más rápidas para validar y eliminar comentarios de archivos XML reales.
Sintaxis de comentarios XML
Un comentario XML abre con `<!--` - un signo menor que, un signo de exclamación y dos guiones - y cierra con `-->` - dos guiones y un signo mayor que. Cada carácter entre esos delimitadores es el contenido del comentario y es completamente ignorado por cualquier parser XML conforme. El contenido puede incluir cualquier marcado XML, valores de atributos, nodos de texto o instrucciones de procesamiento: nada de ello se parsea ni ejecuta.
Las tres formas válidas de comentario
Los tres patrones siguientes son XML correcto. Solo difieren en cómo elijas disponer el contenido, no en distinción sintáctica significativa alguna:
- Comentario en línea: `<!-- This is a comment -->` - colocado en la misma línea que un elemento
- Línea de comentario independiente: `<!-- Full line is a comment -->` - en su propia línea entre elementos
- Bloque de comentario multilínea: `<!--` en una línea, texto del comentario en varias líneas, `-->` en la línea final
Note
Cómo lucen los comentarios en el DOM
Cuando un parser XML construye un árbol de documento, los comentarios se representan como nodos Comment - un tipo de nodo distinto separado de los nodos Element, Text y Attribute. Esto significa que el código de librería puede acceder a los nodos de comentario si así lo decide, aunque no lleven significado de datos. Los métodos estándar de recorrido del DOM que iteran elementos hijos omiten los nodos de comentario automáticamente; solo las consultas explícitas de nodos de comentario los devuelven.
Dónde se permiten los comentarios XML
Los comentarios XML son válidos en más posiciones de las que la mayoría de desarrolladores espera, pero hay un puñado de ubicaciones exactas donde la especificación los prohíbe. Entender estos límites evita fallos de parseo confusos que no mencionan comentarios en absoluto en sus mensajes de error.
Posiciones válidas
- Antes del elemento raíz: los comentarios pueden aparecer tras la declaración XML y antes de la primera etiqueta de apertura
- Entre elementos hijos: cualquier posición de espacio en blanco entre elementos hermanos acepta un comentario
- Después del elemento raíz: el epílogo XML (tras la etiqueta de cierre raíz) acepta comentarios e instrucciones de procesamiento
- Dentro del contenido de un elemento: un comentario colocado entre una etiqueta padre y sus hijos es válido
- Entre atributos en líneas separadas: un comentario no puede aparecer dentro de una etiqueta, pero sí entre elementos cuyos atributos abarcan varias líneas
Posiciones prohibidas
Los comentarios están prohibidos dentro de las etiquetas de elemento - entre el nombre de etiqueta y el cierre `>`, dentro de valores de atributos y dentro de instrucciones de procesamiento. También están prohibidos antes de la propia declaración XML. Colocar `<!-- comment -->` dentro de una etiqueta de apertura como `<config <!-- note --> key="value">` es un error de buena formación que todo parser XML rechaza. La declaración XML `<?xml version="1.0"?>` también debe aparecer antes de cualquier comentario si es que aparece.
| Ubicación | Ejemplo | ¿Válido? |
|---|---|---|
| Antes del elemento raíz | <!-- doc header -->\n<root> | ✓ Sí |
| Entre elementos hijos | <a/> <!-- note --> <b/> | ✓ Sí |
| Después del elemento raíz | </root>\n<!-- footer --> | ✓ Sí |
| Dentro del contenido de un elemento | <p>text <!-- note --> more</p> | ✓ Sí |
| Dentro de una etiqueta de apertura | <elem <!-- note --> attr="v"> | ✗ No - error de parseo |
| Dentro de un valor de atributo | <elem attr="v <!-- note -->"> | ✗ No - texto literal |
| Antes de la declaración XML | <!-- note -->\n<?xml version="1.0"?> | ✗ No - error de parseo |
| Dentro de una sección CDATA | <![CDATA[ <!-- not a comment --> ]]> | ✗ No - texto literal |
Warning
Cómo comentar bloques XML paso a paso
Comentar un bloque de XML es el uso más común de los comentarios XML - desactivar temporalmente configuración, eliminar un elemento durante la depuración o preservar un valor alternativo sin borrarlo. El proceso es sencillo, pero la restricción del doble guion añade una comprobación extra que debes hacer antes de guardar.
Coloca <!-- antes del bloque
Añade `<!--` en su propia línea inmediatamente antes del primer elemento que quieras desactivar. Colocarlo en una línea separada mantiene el diff limpio y facilita identificar qué líneas están comentadas en la revisión de código. El parser trata todo lo que sigue al `<!--` como contenido del comentario hasta encontrar el `-->` correspondiente.
Escanea el bloque en busca de dobles guiones
Antes de añadir el cierre `-->`, escanea cada línea del bloque en busca de cualquier secuencia `--`. La especificación XML establece que `--` no está permitido dentro del contenido del comentario - termina el comentario prematuramente y causa un error de buena formación. Fuentes comunes de dobles guiones en contenido XML incluyen fragmentos SQL en archivos de configuración de bases de datos, números de versión como `1.0--beta` y documentación copiada que usa rayas codificadas como dos guiones.
Coloca --> después del bloque
Añade `-->` en su propia línea inmediatamente después del último elemento que quieras desactivar. El parser reanuda el procesamiento normal desde el carácter posterior al `-->`. Si estás comentando el último elemento de un documento, asegúrate de que `-->` aparezca antes de la etiqueta de cierre raíz - no después, lo que situaría el comentario en la posición del epílogo.
Valida el resultado
Pasa el documento modificado por el comprobador de buena formación XML para confirmar que el comentario está correctamente colocado y que el documento circundante sigue parseando. El comprobador reporta la línea y columna exactas de cualquier error de buena formación introducido por el comentario, incluida la violación del doble guion si existe.
Comprobador de Buena Formación XML
Valida cualquier documento XML en busca de errores a nivel de parser - etiquetas mal formadas, entidades inválidas, comentarios mal colocados y violaciones del doble guion - con diagnósticos a nivel de línea en tu navegador.
Restricciones y trampas de los comentarios XML
La especificación XML impone tres restricciones sobre el contenido de los comentarios que no tienen equivalente en la mayoría de otros sistemas de comentarios. Cada una causa un error específico e identificable - y conocerlas evita horas de depuración confusa.
La prohibición del doble guion
La especificación XML 1.0 (sección 2.5) establece: «la cadena `--` (doble guion) no debe aparecer dentro de los comentarios». Esto significa que dos guiones adyacentes cualesquiera dentro de tu contenido de comentario - independientemente del contexto - causarán un error de parseo o terminarán el comentario en la ubicación incorrecta, dejando tu marcado supuestamente desactivado activo en el documento. Esta regla pilla a muchos desarrolladores desprevenidos porque `--` es una secuencia común en SQL, scripts de shell y cadenas de opciones CLI que aparecen frecuentemente en archivos de configuración.
Warning
Los comentarios anidados están prohibidos
A diferencia de algunos lenguajes de programación, los comentarios XML no pueden anidarse. Intentar envolver un bloque ya comentado en otro par `<!-- -->` hace que el primer `-->` dentro del bloque cierre el comentario externo, dejando el resto como contenido activo. Este es el error más común relacionado con comentarios al trabajar con archivos de configuración grandes donde los bloques pueden contener ya comentarios de documentación. La solución es eliminar los comentarios internos antes de aplicar un bloque de comentario externo.
Los comentarios no pueden terminar con triple guion
Una restricción relacionada: la secuencia de cierre de comentario `-->` no debe ir precedida de un guion, lo que hace `--->` inválido. Esto significa que un comentario como `<!-- note --->` es un error de buena formación. Algunos parsers permisivos lo aceptan silenciosamente; los parsers estrictos conformes a la especificación lanzan un error de «comentario mal formado». Cierra siempre los comentarios exactamente con `-->` y sin guiones extra.
Por compatibilidad, la cadena `--` (doble guion) no debe aparecer dentro de los comentarios. Los comentarios no forman parte de los datos de caracteres del documento.
Comentarios XML por tipo de archivo
Los comentarios XML aparecen en decenas de formatos de archivo en diferentes ecosistemas. La misma sintaxis `<!-- -->` aplica en todas partes, pero los casos de uso prácticos y los patrones de contenido que crean problemas de doble guion varían según el tipo de archivo.
Archivos pom.xml de Maven y de build de Gradle
Los archivos POM de Maven están entre los archivos XML más comentados del desarrollo Java empresarial. Los equipos usan comentarios para documentar decisiones de dependencias, explicar la configuración de plugins y preservar versiones alternativas de dependencias para cambios rápidos. El problema más común en archivos POM es comentar un bloque `<dependency>` que ya tiene un comentario XML dentro - el `-->` interno cierra el bloque de comentario externo prematuramente. Elimina los comentarios internos antes de envolver el bloque. Usa el comprobador de buena formación XML después de editar para confirmar que el archivo sigue parseando.
Archivos de layout y manifest de Android
Los layouts XML de Android y los archivos `AndroidManifest.xml` siguen las mismas reglas de comentario XML. Un patrón común es comentar un bloque entero `<activity>` o `<uses-permission>` durante el desarrollo para probar diferentes configuraciones. Como estos archivos son procesados por el compilador de recursos de Android antes de incluirse en el APK, los comentarios se eliminan en tiempo de build - no tienen impacto en runtime. Los comentarios no pueden aparecer dentro de valores de atributos, así que anotar ajustes individuales de atributos requiere colocar el comentario en una línea separada encima del atributo.
Archivos SVG
SVG es un vocabulario XML, así que los comentarios usan la misma sintaxis `<!-- -->`. Se usan comúnmente para documentar secciones de artboard, etiquetar capas y preservar definiciones alternativas de trazados. Los comentarios SVG se preservan cuando el archivo es cargado por un navegador como `<svg>` en línea o vía etiqueta `<img>` - aparecen en el DOM y pueden inspeccionarse en DevTools. Si estás optimizando un SVG para producción, usa el eliminador de comentarios XML para eliminar comentarios y reducir el tamaño del archivo antes de desplegar.
Hojas de estilo XSLT
Las hojas de estilo XSLT son documentos XML que transforman otros documentos XML. Los comentarios en XSLT se usan para desactivar reglas de plantilla durante la depuración y documentar expresiones XPath complejas. Como los procesadores XSLT ejecutan la hoja de estilo como XML, una regla `<xsl:template>` comentada está completamente inactiva. Combínalo con el buscador y probador de XPath para verificar tus expresiones XPath antes de descomentar una regla de plantilla.
Configuración XML de Spring
Los archivos de configuración de beans XML de Spring Framework son documentos XML grandes y jerárquicamente estructurados donde los comentarios se usan extensivamente para documentar ámbitos de beans, explicar decisiones de inyección de dependencias y preservar configuraciones heredadas. La restricción del doble guion es particularmente relevante en archivos Spring que referencian cadenas de conexión a bases de datos o plantillas SQL - ambos contienen frecuentemente secuencias `--`. Escanea siempre el contenido antes de comentarlo y reemplaza cualquier `--` con un guion simple o una frase descriptiva.
Eliminar comentarios XML para producción
Los comentarios XML destinados a documentación de desarrolladores no deberían llegar a producción en todos los contextos. Eliminarlos reduce el tamaño del payload, remueve notas internas de feeds públicamente accesibles y elimina el marginal sobrecoste de parseo de los nodos de comentario en pipelines de procesamiento XML de alto rendimiento.
Cuándo eliminar comentarios XML
- Feeds RSS y Atom: los comentarios añaden bytes a feeds públicamente accesibles sin beneficio alguno para los lectores de feeds
- Payloads de API SOAP: algunos parsers XML usados por consumidores SOAP empresariales tienen políticas estrictas de cero comentarios
- Assets SVG desplegados en producción: los comentarios aumentan el tamaño del archivo y son visibles para cualquiera que inspeccione el código fuente
- Archivos de configuración XML en imágenes de contenedores: elimina comentarios para reducir el tamaño de la imagen Docker y prevenir fugas de documentación interna
- Archivos de datos XML en pipelines ETL: eliminarlos antes de la ingesta reduce el tiempo de parseo y evita el manejo inesperado de nodos de comentario por procesadores posteriores
Eliminador de Comentarios XML
Elimina todos los comentarios XML de cualquier documento al instante - salida limpia lista para APIs, despliegue u optimización de tamaño. Se ejecuta enteramente en tu navegador sin subidas.
Eliminación programática
En Python, la librería `lxml` proporciona eliminación de comentarios vía `lxml.etree.strip_tags` con el tipo de comentario, o puedes iterar todos los nodos de comentario y llamar a `remove()`. La librería estándar `xml.etree.ElementTree` descarta los comentarios por defecto al parsear - no aparecen en el árbol de elementos en absoluto. En Node.js, la librería `fast-xml-parser` ignora los comentarios durante el parseo, y la librería `xml2js` hace lo mismo con la configuración por defecto. Para un enfoque rápido sin código, el eliminador de comentarios XML maneja cualquier documento XML en tu navegador sin requerir configuración de librerías.
Note
Buenas prácticas de comentarios XML
Los comentarios XML bien estructurados hacen los archivos de configuración significativamente más fáciles de mantener, revisar y traspasar. Estos patrones aparecen en archivos POM de Maven, configs XML de Spring, assets SVG y manifestos de Android en bases de código profesionales.
Documenta la intención, no la mecánica
Un comentario que repite lo que hace un elemento no añade valor. Un comentario que explica por qué el elemento está configurado así es genuinamente útil. En un POM de Maven, un comentario como `<!-- Pinned to 3.2.1 because 3.3.0 broke transaction rollback on Oracle 19c -->` le dice al siguiente desarrollador exactamente lo que necesita saber antes de actualizar la dependencia. El número de versión en bruto solo, no.
Comentarios cortos y encima, no al lado
Los elementos XML frecuentemente tienen listas de atributos largas que abarcan varias líneas. Un comentario en línea colocado tras un atributo hace la línea aún más larga y rompe el formato. La convención estándar en archivos XML es colocar los comentarios explicativos en una línea dedicada encima del elemento que describen, no en la misma línea. Esto también asegura que el comentario es válido - recuerda que los comentarios dentro de etiquetas están prohibidos sin importar la longitud de la línea.
- Bien: comentario en su propia línea encima del elemento - `<!-- Required for SSO login flow -->\n<property name="authProvider" value="saml"/>`
- Evita: comentario tras un atributo en la misma línea de etiqueta - causa un error de buena formación
- Bien: comentarios separadores de sección - `<!-- ═══ Database Configuration ═══ -->` antes de un grupo lógico de beans
- Evita: código comentado dejado en archivos indefinidamente - archívalo en el control de versiones en lugar de mantener marcado muerto
- Bien: eliminar secuencias `--` del código comentado antes de hacer commit - previene futuros errores de buena formación
Tip
Valida tras convertir hacia o desde otros formatos
Si conviertes un config JSON o YAML a XML usando el convertidor de XML a JSON o una herramienta similar, la salida no llevará comentarios del fuente - los comentarios JSON y YAML no se preservan en la conversión. Añade cualquier comentario de documentación XML manualmente tras la conversión, y luego valida el resultado. A la inversa, si conviertes XML a YAML, los comentarios se descartan porque el convertidor lee el árbol DOM parseado, no el texto fuente en bruto. Mantén el XML original como fuente autoritativa cuando los comentarios de documentación sean importantes.
Key takeaways
- XML tiene exactamente una sintaxis de comentario: `<!-- comment -->`. No hay formas alternativas.
- Los comentarios no pueden aparecer dentro de etiquetas de apertura o cierre de elementos, dentro de valores de atributos, ni antes de la declaración XML.
- La secuencia `--` (doble guion) está prohibida dentro del contenido de comentarios XML - termina el comentario prematuramente y causa un error de buena formación.
- Los comentarios XML no pueden anidarse - el primer `-->` dentro de un bloque siempre cierra el comentario abierto más externo.
- Usa el comprobador de buena formación XML después de añadir comentarios para detectar violaciones del doble guion y comentarios mal colocados.
- Elimina los comentarios antes de desplegar a producción usando el eliminador de comentarios XML - los comentarios se preservan en el fuente pero no añaden valor a los artefactos desplegados.
- Coloca los comentarios en sus propias líneas encima de los elementos que describen - nunca dentro de una etiqueta ni tras un valor de atributo en la misma línea.