XML possède exactement une syntaxe de commentaire : la paire de délimiteurs <!-- -->. Contrairement à YAML ou Python, il n'y a pas de forme abrégée, pas de raccourci au niveau de la ligne, pas de forme alternative. Ce que XML offre, c'est de la flexibilité — le même délimiteur fonctionne pour les notes d'une ligne, les blocs de documentation multi-paragraphes et la désactivation temporaire de sections entières de balisage. Ce guide couvre la syntaxe complète, chaque emplacement où les commentaires XML sont interdits, la restriction du double tiret qui déroute la plupart des développeurs, et les outils les plus rapides pour valider et supprimer les commentaires de fichiers XML réels.
Syntaxe des commentaires XML
Un commentaire XML s'ouvre avec `<!--` - un signe inférieur, un point d'exclamation et deux tirets - et se ferme avec `-->` - deux tirets et un signe supérieur. Chaque caractère entre ces délimiteurs est le contenu du commentaire et est totalement ignoré par tout parseur XML conforme. Le contenu peut inclure du balisage XML, des valeurs d'attributs, des nœuds texte ou des instructions de traitement : rien de tout cela n'est analysé ni exécuté.
Les trois formes de commentaires valides
Les trois motifs suivants sont du XML correct. Ils ne diffèrent que par la façon dont vous choisissez de disposer le contenu, sans distinction syntaxique significative :
- Commentaire en ligne : `<!-- This is a comment -->` - placé sur la même ligne qu'un élément
- Ligne de commentaire autonome : `<!-- Full line is a comment -->` - sur sa propre ligne entre les éléments
- Bloc de commentaire multi-lignes : `<!--` sur une ligne, texte du commentaire sur plusieurs lignes, `-->` sur la dernière ligne
Note
À quoi ressemblent les commentaires dans le DOM
Lorsqu'un parseur XML construit un arbre de document, les commentaires sont représentés comme des nœuds Comment - un type de nœud distinct, séparé des nœuds Element, Text et Attribute. Cela signifie que le code de bibliothèque peut accéder aux nœuds de commentaire s'il le choisit, même s'ils ne portent aucun sens de données. Les méthodes standard de parcours du DOM qui itèrent les éléments enfants sautent automatiquement les nœuds de commentaire ; seules les requêtes explicites de nœuds de commentaire les retournent.
Où les commentaires XML sont autorisés
Les commentaires XML sont valides dans plus de positions que la plupart des développeurs ne l'attendent, mais il existe un petit nombre d'emplacements exacts où la spécification les interdit. Comprendre ces limites évite des échecs d'analyse déroutants qui ne mentionnent pas du tout les commentaires dans leurs messages d'erreur.
Positions valides
- Avant l'élément racine : les commentaires peuvent apparaître après la déclaration XML et avant la première balise ouvrante
- Entre éléments enfants : toute position d'espace entre éléments frères accepte un commentaire
- Après l'élément racine : l'épilogue XML (après la balise racine fermante) accepte les commentaires et les instructions de traitement
- Dans le contenu d'un élément : un commentaire placé entre une balise parente et ses enfants est valide
- Entre attributs sur des lignes séparées : un commentaire ne peut pas apparaître à l'intérieur d'une balise, mais peut apparaître entre des éléments dont les attributs s'étendent sur plusieurs lignes
Positions interdites
Les commentaires sont interdits à l'intérieur des balises d'élément - entre le nom de balise et le `>` fermant, à l'intérieur des valeurs d'attributs, et à l'intérieur des instructions de traitement. Ils sont aussi interdits avant la déclaration XML elle-même. Placer `<!-- comment -->` à l'intérieur d'une balise ouvrante comme `<config <!-- note --> key="value">` est une erreur de bonne formation que tout parseur XML rejette. La déclaration XML `<?xml version="1.0"?>` doit également apparaître avant tout commentaire si elle apparaît.
| Emplacement | Exemple | Valide ? |
|---|---|---|
| Avant l'élément racine | <!-- doc header -->\n<root> | ✓ Oui |
| Entre éléments enfants | <a/> <!-- note --> <b/> | ✓ Oui |
| Après l'élément racine | </root>\n<!-- footer --> | ✓ Oui |
| Dans le contenu d'un élément | <p>text <!-- note --> more</p> | ✓ Oui |
| Dans une balise ouvrante | <elem <!-- note --> attr="v"> | ✗ Non - erreur d'analyse |
| Dans une valeur d'attribut | <elem attr="v <!-- note -->"> | ✗ Non - texte littéral |
| Avant la déclaration XML | <!-- note -->\n<?xml version="1.0"?> | ✗ Non - erreur d'analyse |
| Dans une section CDATA | <![CDATA[ <!-- not a comment --> ]]> | ✗ Non - texte littéral |
Warning
Commenter des blocs XML étape par étape
Mettre un bloc XML en commentaire est l'usage le plus courant des commentaires XML - désactiver temporairement une configuration, retirer un élément pendant le débogage, ou préserver une valeur alternative sans la supprimer. Le processus est simple, mais la restriction du double tiret ajoute une vérification supplémentaire à effectuer avant d'enregistrer.
Placez <!-- avant le bloc
Ajoutez `<!--` sur sa propre ligne immédiatement avant le premier élément que vous voulez désactiver. Le placer sur une ligne séparée garde le diff propre et facilite l'identification des lignes commentées lors de la revue de code. Le parseur traite tout ce qui suit `<!--` comme contenu de commentaire jusqu'à trouver le `-->` correspondant.
Scannez le bloc à la recherche de doubles tirets
Avant d'ajouter le `-->` fermant, scannez chaque ligne du bloc à la recherche de toute séquence `--`. La spécification XML stipule que `--` n'est pas permis à l'intérieur du contenu d'un commentaire - il termine le commentaire prématurément et provoque une erreur de bonne formation. Les sources courantes de doubles tirets dans le contenu XML incluent des extraits SQL dans les fichiers de configuration de bases de données, des numéros de version comme `1.0--beta`, et de la documentation copiée utilisant des tirets cadratins encodés en deux tirets.
Placez --> après le bloc
Ajoutez `-->` sur sa propre ligne immédiatement après le dernier élément que vous voulez désactiver. Le parseur reprend le traitement normal à partir du caractère suivant `-->`. Si vous commentez le dernier élément d'un document, assurez-vous que `-->` apparaisse avant la balise racine fermante - pas après, ce qui placerait le commentaire en position d'épilogue.
Validez le résultat
Passez le document modifié par le vérificateur de bonne formation XML pour confirmer que le commentaire est correctement placé et que le document environnant s'analyse toujours. Le vérificateur rapporte la ligne et la colonne exactes de toute erreur de bonne formation introduite par le commentaire, y compris la violation du double tiret s'il y en a une.
Vérificateur de Bonne Formation XML
Validez tout document XML pour les erreurs au niveau du parseur - balises mal formées, entités invalides, commentaires mal placés et violations du double tiret - avec des diagnostics au niveau de la ligne dans votre navigateur.
Restrictions et pièges des commentaires XML
La spécification XML impose trois restrictions au contenu des commentaires qui n'ont pas d'équivalent dans la plupart des autres systèmes de commentaires. Chacune provoque une erreur spécifique et identifiable - et les connaître évite des heures de débogage confus.
L'interdiction du double tiret
La spécification XML 1.0 (section 2.5) stipule : « la chaîne `--` (double tiret) ne doit pas apparaître dans les commentaires. » Cela signifie que deux tirets adjacents quelconques à l'intérieur de votre contenu de commentaire - quel que soit le contexte - provoqueront soit une erreur d'analyse, soit termineront le commentaire au mauvais endroit, laissant votre balisage supposément désactivé actif dans le document. Cette règle prend de nombreux développeurs au dépourvu car `--` est une séquence courante en SQL, dans les scripts shell et dans les chaînes d'options CLI qui apparaissent fréquemment dans les fichiers de configuration.
Warning
Les commentaires imbriqués sont interdits
Contrairement à certains langages de programmation, les commentaires XML ne peuvent pas être imbriqués. Tenter d'envelopper un bloc déjà commenté dans une autre paire `<!-- -->` fait que le premier `-->` à l'intérieur du bloc ferme le commentaire externe, laissant le reste comme contenu actif. C'est l'erreur liée aux commentaires la plus courante lorsqu'on travaille avec de grands fichiers de configuration où les blocs peuvent déjà contenir des commentaires de documentation. La solution consiste à retirer les commentaires internes avant d'appliquer un bloc de commentaire externe.
Les commentaires ne peuvent pas se terminer par un triple tiret
Une restriction connexe : la séquence de fermeture `-->` ne doit pas être précédée d'un tiret, ce qui rend `--->` invalide. Cela signifie qu'un commentaire comme `<!-- note --->` est une erreur de bonne formation. Certains parseurs indulgents l'acceptent silencieusement ; les parseurs stricts conformes à la spec lèvent une erreur de « commentaire mal formé ». Fermez toujours les commentaires exactement avec `-->` et sans tiret supplémentaire.
Pour la compatibilité, la chaîne `--` (double tiret) ne doit pas apparaître dans les commentaires. Les commentaires ne font pas partie des données de caractères du document.
Commentaires XML par type de fichier
Les commentaires XML apparaissent dans des dizaines de formats de fichiers à travers différents écosystèmes. La même syntaxe `<!-- -->` s'applique partout, mais les cas d'usage pratiques et les motifs de contenu qui créent des problèmes de double tiret varient selon le type de fichier.
Fichiers pom.xml Maven et fichiers de build Gradle
Les fichiers POM Maven comptent parmi les fichiers XML les plus commentés du développement Java d'entreprise. Les équipes utilisent les commentaires pour documenter les décisions de dépendances, expliquer la configuration des plugins et préserver des versions alternatives de dépendances pour des changements rapides. Le problème le plus courant dans les fichiers POM est de commenter un bloc `<dependency>` qui contient déjà un commentaire XML - le `-->` interne ferme le bloc de commentaire externe prématurément. Retirez les commentaires internes avant d'envelopper le bloc. Utilisez le vérificateur de bonne formation XML après édition pour confirmer que le fichier s'analyse toujours.
Fichiers de layout et manifest Android
Les layouts XML d'Android et les fichiers `AndroidManifest.xml` suivent les mêmes règles de commentaires XML. Un motif courant consiste à commenter un bloc entier `<activity>` ou `<uses-permission>` pendant le développement pour tester différentes configurations. Comme ces fichiers sont traités par le compilateur de ressources d'Android avant d'être inclus dans l'APK, les commentaires sont retirés au moment du build - ils n'ont aucun impact à l'exécution. Les commentaires ne peuvent pas apparaître à l'intérieur des valeurs d'attributs, donc annoter des réglages d'attributs individuels exige de placer le commentaire sur une ligne séparée au-dessus de l'attribut.
Fichiers SVG
SVG est un vocabulaire XML, donc les commentaires utilisent la même syntaxe `<!-- -->`. Ils sont couramment utilisés pour documenter des sections de planche graphique, étiqueter des calques et préserver des définitions alternatives de tracés. Les commentaires SVG sont préservés lorsque le fichier est chargé par un navigateur comme `<svg>` en ligne ou via une balise `<img>` - ils apparaissent dans le DOM et peuvent être inspectés dans les DevTools. Si vous optimisez un SVG pour la production, utilisez le suppresseur de commentaires XML pour retirer les commentaires et réduire la taille du fichier avant le déploiement.
Feuilles de style XSLT
Les feuilles de style XSLT sont des documents XML qui transforment d'autres documents XML. Les commentaires en XSLT servent à désactiver des règles de template pendant le débogage et à documenter des expressions XPath complexes. Comme les processeurs XSLT exécutent la feuille de style comme du XML, une règle `<xsl:template>` commentée est totalement inactive. Associez cela au chercheur et testeur XPath pour vérifier vos expressions XPath avant de décommenter une règle de template.
Configuration XML de Spring
Les fichiers de configuration de beans XML de Spring Framework sont de grands documents XML hiérarchiquement structurés où les commentaires sont largement utilisés pour documenter les scopes de beans, expliquer les choix d'injection de dépendances et préserver les configurations historiques. La restriction du double tiret est particulièrement pertinente dans les fichiers Spring qui référencent des chaînes de connexion à des bases de données ou des templates SQL - les deux contiennent fréquemment des séquences `--`. Scannez toujours le contenu avant de le commenter et remplacez tout `--` par un tiret simple ou une phrase descriptive.
Supprimer les commentaires XML pour la production
Les commentaires XML destinés à la documentation développeur ne devraient pas voyager jusqu'en production dans tous les contextes. Les supprimer réduit la taille des payloads, retire les notes internes des flux publiquement accessibles et élimine le surcoût d'analyse marginal des nœuds de commentaire dans les pipelines de traitement XML à haut débit.
Quand supprimer les commentaires XML
- Flux RSS et Atom : les commentaires ajoutent des octets à des flux publiquement accessibles sans aucun bénéfice pour les lecteurs de flux
- Payloads d'API SOAP : certains parseurs XML utilisés par des consommateurs SOAP d'entreprise ont des politiques strictes de zéro commentaire
- Assets SVG déployés en production : les commentaires augmentent la taille du fichier et sont visibles par quiconque inspecte le code source
- Fichiers de configuration XML dans les images de conteneurs : supprimez les commentaires pour réduire la taille de l'image Docker et éviter les fuites de documentation interne
- Fichiers de données XML dans les pipelines ETL : les supprimer avant l'ingestion réduit le temps d'analyse et évite la gestion inattendue des nœuds de commentaire par les processeurs en aval
Suppresseur de Commentaires XML
Supprimez tous les commentaires XML de tout document instantanément - sortie propre prête pour les API, le déploiement ou l'optimisation de taille. Fonctionne entièrement dans votre navigateur sans téléversement.
Suppression programmatique
En Python, la bibliothèque `lxml` fournit la suppression de commentaires via `lxml.etree.strip_tags` avec le type commentaire, ou vous pouvez itérer tous les nœuds de commentaire et appeler `remove()`. La bibliothèque standard `xml.etree.ElementTree` ignore les commentaires par défaut lors de l'analyse - ils n'apparaissent pas du tout dans l'arbre d'éléments. En Node.js, la bibliothèque `fast-xml-parser` ignore les commentaires pendant l'analyse, et la bibliothèque `xml2js` fait de même avec la configuration par défaut. Pour une approche rapide sans code, le suppresseur de commentaires XML gère tout document XML dans votre navigateur sans aucune configuration de bibliothèque.
Note
Bonnes pratiques des commentaires XML
Des commentaires XML bien structurés rendent les fichiers de configuration nettement plus faciles à maintenir, réviser et transmettre. Ces motifs apparaissent dans les fichiers POM Maven, les configs XML Spring, les assets SVG et les manifestes Android dans des bases de code professionnelles.
Documentez l'intention, pas la mécanique
Un commentaire qui répète ce que fait un élément n'apporte aucune valeur. Un commentaire qui explique pourquoi l'élément est configuré ainsi est réellement utile. Dans un POM Maven, un commentaire comme `<!-- Pinned to 3.2.1 because 3.3.0 broke transaction rollback on Oracle 19c -->` indique au développeur suivant exactement ce qu'il doit savoir avant de mettre à jour la dépendance. Le simple numéro de version, non.
Gardez les commentaires courts et au-dessus, pas à côté
Les éléments XML ont fréquemment de longues listes d'attributs qui s'étendent sur plusieurs lignes. Un commentaire en ligne placé après un attribut allonge encore la ligne et casse le formatage. La convention standard dans les fichiers XML est de placer les commentaires explicatifs sur une ligne dédiée au-dessus de l'élément qu'ils décrivent, pas sur la même ligne. Cela garantit aussi que le commentaire est valide - rappelez-vous que les commentaires à l'intérieur des balises sont interdits quelle que soit la longueur de ligne.
- Bien : commentaire sur sa propre ligne au-dessus de l'élément - `<!-- Required for SSO login flow -->\n<property name="authProvider" value="saml"/>`
- À éviter : commentaire après un attribut sur la même ligne de balise - provoque une erreur de bonne formation
- Bien : commentaires séparateurs de section - `<!-- ═══ Database Configuration ═══ -->` avant un groupe logique de beans
- À éviter : du code commenté laissé indéfiniment dans les fichiers - archivez-le dans le contrôle de version au lieu de garder du balisage mort
- Bien : retirer les séquences `--` du code commenté avant de committer - prévient de futures erreurs de bonne formation
Tip
Validez après conversion vers ou depuis d'autres formats
Si vous convertissez une config JSON ou YAML en XML avec le convertisseur XML vers JSON ou un outil similaire, la sortie ne portera pas les commentaires de la source - les commentaires JSON et YAML ne sont pas préservés dans la conversion. Ajoutez manuellement tout commentaire de documentation XML après la conversion, puis validez le résultat. Inversement, si vous convertissez du XML en YAML, les commentaires sont abandonnés car le convertisseur lit l'arbre DOM analysé, pas le texte source brut. Gardez le XML original comme source faisant autorité lorsque les commentaires de documentation sont importants.
Key takeaways
- XML possède exactement une syntaxe de commentaire : `<!-- comment -->`. Il n'y a pas de formes alternatives.
- Les commentaires ne peuvent pas apparaître à l'intérieur des balises ouvrantes ou fermantes d'éléments, à l'intérieur des valeurs d'attributs, ni avant la déclaration XML.
- La séquence `--` (double tiret) est interdite dans le contenu des commentaires XML - elle termine le commentaire prématurément et provoque une erreur de bonne formation.
- Les commentaires XML ne peuvent pas être imbriqués - le premier `-->` à l'intérieur d'un bloc ferme toujours le commentaire ouvert le plus externe.
- Utilisez le vérificateur de bonne formation XML après avoir ajouté des commentaires pour détecter les violations du double tiret et les positions de commentaires mal placées.
- Supprimez les commentaires avant de déployer en production avec le suppresseur de commentaires XML - les commentaires sont préservés dans la source mais n'ajoutent aucune valeur aux artefacts déployés.
- Placez les commentaires sur leurs propres lignes au-dessus des éléments qu'ils décrivent - jamais à l'intérieur d'une balise ni après une valeur d'attribut sur la même ligne.