YAML possède exactement un caractère de commentaire : le symbole dièse. Toutes les autres questions sur les commentaires YAML — comment s'étendre sur plusieurs lignes, où le dièse est interdit, pourquoi votre commentaire en ligne a tronqué une valeur, si les parseurs préservent les commentaires — remontent à la compréhension de cette règle unique et de ses limites. Ce guide couvre tout, de la syntaxe de base aux workflows de production pour supprimer et valider des fichiers YAML commentés.
Bases de la syntaxe des commentaires YAML
En YAML, un commentaire commence par un caractère `#` et s'étend jusqu'à la fin de la ligne. Tout ce qui suit `#` — sur cette ligne uniquement — est ignoré par le parseur. Il n'y a pas de délimiteurs de fermeture, pas de syntaxe de commentaire de bloc, et aucun moyen d'intégrer un commentaire au milieu d'une valeur. Un caractère, une règle, aucune exception.
Le caractère de commentaire et l'espace requis
La spécification YAML comporte une nuance importante qui piège beaucoup de développeurs : un commentaire en ligne doit être précédé d'au moins un caractère d'espacement. Un `#` collé directement à un caractère non espacé n'est pas traité comme un commentaire — il est analysé comme faisant partie de la valeur scalaire environnante. Cela compte surtout quand on ajoute des commentaires après des valeurs sur la même ligne.
- Commentaire en ligne correct : `timeout: 30 # seconds` - l'espace avant `#` est présent
- Commentaire en ligne incorrect : `timeout: 30# seconds` - pas d'espace, `#` devient partie de la valeur
- Ligne de commentaire autonome : `# This whole line is a comment` - aucune valeur avant
- Commentaire indenté : ` # Indented comment inside a block` - l'indentation est acceptable
Warning
Syntaxe des commentaires en un coup d'œil
Voici les trois motifs de placement de commentaires valides en YAML. Toute autre variation est soit identique à l'une de celles-ci, soit invalide :
- Commentaire en début de ligne : `# comment text` - placé en colonne 0 ou après des espaces initiaux
- Commentaire en ligne après un scalaire : `key: value # comment` - un ou plusieurs espaces avant `#`
- Commentaire en ligne après un élément de liste : `- item # comment` - même règle d'espace
Où les commentaires sont autorisés
Les commentaires sont légaux dans la grande majorité des endroits d'un document YAML. Comprendre la poignée d'endroits où ils ne le sont pas vous aide à éviter des erreurs d'analyse déroutantes qui ne mentionnent pas du tout les commentaires.
Positions autorisées
- Avant toute paire clé-valeur : placez les commentaires de documentation au-dessus de la clé sur une ligne dédiée
- Après toute valeur scalaire sur la même ligne : `retries: 3 # max attempts`
- Après un élément de liste : `- production # primary environment`
- Après une clé de mapping (sans valeur) : `database: # configured below`
- Sur les lignes vides entre blocs : utilisez librement des lignes de commentaire comme séparateurs visuels
- En haut du fichier : les commentaires de documentation au niveau du fichier sont courants dans les configs Kubernetes et CI/CD
Les marqueurs de début et fin de document
Les commentaires sont aussi valides avant et après les marqueurs de document YAML `---` (début de document) et `...` (fin de document). Cela permet d'ajouter des commentaires de métadonnées au niveau du fichier avant le corps du document dans des flux YAML multi-documents.
| Emplacement | Exemple | Commentaire autorisé ? |
|---|---|---|
| Ligne autonome | # Full-line comment | ✓ Oui |
| Après valeur scalaire | key: value # note | ✓ Oui (espace requis) |
| Après élément de liste | - item # note | ✓ Oui (espace requis) |
| Avant début de document | # Header\n--- | ✓ Oui |
| Dans une chaîne quotée | "Say # hello" | ✗ Non - # est littéral |
| Dans un scalaire de bloc | |\n line # note | ✗ Non - # est littéral |
| Dans une séquence de flux | [a, b # note, c] | ✗ Non - erreur de syntaxe |
| Dans un mapping de flux | {a: 1 # note, b: 2} | ✗ Peu fiable |
Note
Commentaires multi-lignes et de bloc
YAML n'a pas de syntaxe de commentaire de bloc. Il n'y a pas d'équivalent `/* ... */`, pas de heredoc `#!`, et aucun moyen d'ouvrir un commentaire sur une ligne pour le fermer sur une autre. Pour commenter plusieurs lignes consécutives, vous devez préfixer chaque ligne individuellement avec `#`.
Un commentaire est un caractère dièse suivi de caractères qui n'incluent pas de sauts de ligne, et s'étend jusqu'à - sans inclure - le prochain saut de ligne. Un commentaire est traité comme un espace blanc.
Le motif conventionnel de commentaire de bloc
Les lignes `#` consécutives sont visuellement interprétées comme un commentaire de bloc, même si chaque ligne est techniquement un commentaire de ligne indépendant. C'est la convention universelle dans les fichiers YAML de tous les écosystèmes — Kubernetes, GitHub Actions, Docker Compose, charts Helm et pipelines CI/CD utilisent tous ce motif :
- `# -----------------------------------------`
- `# Database configuration`
- `# Update connection strings before deploying`
- `# -----------------------------------------`
Raccourcis éditeur pour commenter plusieurs lignes
Chaque éditeur de code majeur permet de basculer les commentaires sur plusieurs lignes sélectionnées dans des fichiers YAML. Sélectionnez les lignes à commenter, puis utilisez le raccourci de bascule — l'éditeur ajoute ou retire `#` au début de chaque ligne sélectionnée simultanément. Commenter plusieurs lignes en YAML devient ainsi aussi rapide que dans n'importe quel autre langage.
- VS Code : Ctrl+/ (Windows/Linux) ou Cmd+/ (macOS) - bascule # sur les lignes sélectionnées
- IDE JetBrains (IntelliJ, PyCharm, GoLand) : Ctrl+/ ou Cmd+/ - même comportement
- Vim/Neovim : mode bloc visuel (Ctrl+V), sélectionnez les lignes, I, tapez #, Échap
- Emacs : M-; ou comment-region avec un mode YAML installé
- Sublime Text / TextMate : Ctrl+/ ou Cmd+/ - bascule # sur toutes les lignes sélectionnées
Tip
Où les commentaires cassent tout
Les commentaires sont sûrs dans la plupart des contextes YAML, mais il existe quatre situations spécifiques où un `#` mal placé produira soit une erreur de données silencieuse, soit un échec d'analyse brutal. Les connaître à l'avance évite des heures de débogage confus.
Dans les chaînes quotées
Un `#` dans une chaîne entre guillemets simples ou doubles est toujours un caractère littéral, jamais un commentaire. `message: "Hello # world"` stocke la chaîne `Hello # world`. C'est correct et intentionnel. Le problème survient avec les chaînes non quotées : `message: Hello # world` stocke `Hello` et traite `# world` comme un commentaire — tronquant silencieusement votre valeur. Quotez toute valeur de chaîne non quotée qui contient légitimement un `#`.
Dans les scalaires de bloc (littéral | et plié >)
Dans le contenu d'un scalaire de bloc — les lignes indentées qui suivent un indicateur `|` ou `>` — le caractère `#` n'a aucune signification spéciale. Il est traité comme un caractère littéral et inclus dans la chaîne. Vous ne pouvez pas commenter des lignes dans un scalaire de bloc. Si vous devez exclure du contenu, vous devez le supprimer entièrement plutôt que le commenter.
Dans les collections de flux ([ ] et { })
Les séquences et mappings de flux s'écrivent sur une seule ligne. Placer un dièse dans une collection de flux constitue soit une erreur de syntaxe, soit produit un résultat d'analyse inattendu selon le parseur. Si vous devez annoter des éléments individuels d'une collection de flux, convertissez-la en style bloc (un élément par ligne) où les commentaires en ligne fonctionnent correctement.
Dièse nu sans espace précédent
Comme vu dans la section des bases, un `#` non précédé d'un espace n'est pas reconnu comme commentaire par les parseurs conformes à la spec. La valeur `port: 8080#dev` est analysée comme la chaîne `8080#dev`, pas comme l'entier `8080` avec un commentaire. Écrivez toujours `port: 8080 # dev` avec l'espace.
Warning
Supprimer les commentaires pour la production
Les fichiers YAML destinés aux développeurs sont souvent abondamment commentés à des fins de documentation. Ces mêmes fichiers peuvent devoir être transmis à des API, outils de déploiement ou systèmes de gestion de configuration qui rejettent les commentaires ou ajoutent une surcharge d'analyse inutile. Supprimer les commentaires avant transmission est la solution propre.
Quand vous devez supprimer les commentaires
- Points d'API qui rejettent le YAML commenté - certaines API REST analysent des corps de requête YAML et échouent avec des commentaires
- Allers-retours de sérialisation de config - charger puis réécrire du YAML avec des parseurs standard supprime silencieusement les commentaires
- Réduction du bruit de diff - lors de la revue de changements de config, les diffs YAML sans commentaires se concentrent sur les vrais changements de valeur
- Optimisation de taille de fichier - les manifestes Kubernetes très commentés peuvent être sensiblement plus petits sans commentaires
- Pipelines de traitement automatisés - les scripts qui transforment du YAML ont souvent besoin d'une entrée propre sans logique de gestion des commentaires
Suppresseur de Commentaires YAML
Collez n'importe quel document YAML et supprimez tous les commentaires instantanément - sortie propre prête à copier, télécharger ou transmettre à une API. Fonctionne entièrement dans votre navigateur sans téléversement.
Ce que la suppression de commentaires change et ne change pas
Un outil correct de suppression de commentaires ne retire que le texte du commentaire — le `#` et tout ce qui suit sur cette ligne — sans altérer aucune valeur, clé, indentation ni structure. Les lignes de commentaire autonomes sont remplacées par des lignes vides ou supprimées entièrement. Le YAML résultant s'analyse de manière identique à l'original pour toutes les valeurs de données.
Note
Suppression via le code (Python et Node.js)
Si vous devez supprimer les commentaires programmatiquement dans un pipeline, l'approche la plus simple dans toute bibliothèque YAML standard est un aller-retour charger-puis-écrire : analysez le YAML en structure de données puis sérialisez-le immédiatement. Les commentaires sont ignorés au chargement et jamais écrits à l'écriture. La sortie est du YAML valide avec des données identiques mais sans commentaires. En Python, `PyYAML` fait cela en deux lignes. Pour Node.js, `js-yaml` fait de même.
Motifs de commentaires YAML du monde réel
Les fichiers YAML bien commentés suivent des motifs cohérents qui facilitent leur maintenance, leur revue et leur transmission à d'autres membres de l'équipe. Ces motifs apparaissent dans les manifestes Kubernetes, les workflows GitHub Actions, les fichiers Docker Compose et les fichiers values des charts Helm.
Commentaires d'en-tête de fichier
Placez un bloc de commentaires tout en haut du fichier pour documenter son but, son responsable et tout contexte critique qui n'est pas évident du seul contenu. C'est une pratique standard dans les manifestes Kubernetes et les playbooks Ansible. Le bloc de commentaires comprend typiquement le but du fichier, la date de dernière modification et un lien vers la documentation ou les tickets associés.
Commentaires séparateurs de sections
Les longs fichiers YAML — en particulier `docker-compose.yml` et les `values.yaml` Helm avec des dizaines de clés de premier niveau — gagnent en séparateurs visuels de section qui aident les lecteurs à s'orienter. Une ligne de `# -----------------------------------------------` ou `# === DATABASE CONFIG ===` avant un groupe logique de clés est une convention largement adoptée. Utilisez le validateur d'ancres et d'alias YAML pour vérifier que vos ancres et alias sont corrects lors de la restructuration de fichiers très commentés.
Documentation en ligne pour les valeurs non évidentes
Les commentaires en ligne sont les plus utiles pour les valeurs qui ne s'expliquent pas d'elles-mêmes — nombres magiques, surcharges spécifiques à un environnement, valeurs en unités non évidentes ou champs avec interdépendances. Un commentaire comme `timeout: 300 # seconds; must match nginx keepalive_timeout` est bien plus utile que la valeur seule. Quand vous travaillez avec la substitution de variables d'environnement dans les configs YAML, l'outil d'aperçu de substitution d'env YAML peut vous aider à vérifier comment les valeurs par défaut commentées interagissent avec les surcharges à l'exécution.
- Documentez les unités : `memory: 512 # MB - increase to 1024 for production`
- Signalez les interdépendances : `enabled: false # also disable in config/prod.yaml`
- Expliquez les valeurs par défaut : `workers: 4 # matches CPU core count on t3.medium`
- Avertissez des changements requis : `host: localhost # CHANGE before deploying`
- Référencez des docs externes : `algorithm: RS256 # see RFC 7518, section 3.3`
Tip
Valider le YAML commenté
Ajouter des commentaires à un fichier YAML crée de nouvelles occasions d'erreurs de syntaxe qui ne sont pas immédiatement évidentes — un `#` dans une chaîne non quotée, un espace manquant avant un commentaire en ligne, ou un commentaire accidentel dans un scalaire de bloc. Exécuter un validateur après avoir modifié un fichier YAML commenté est une assurance rapide contre ces problèmes.
Ce que le validateur YAML détecte
Le validateur YAML analyse votre document selon la spécification YAML 1.2 et signale toute erreur de syntaxe avec les numéros de ligne et de colonne. Il détecte les commentaires mal placés, les erreurs d'indentation introduites en ajoutant des lignes de commentaire, les clés dupliquées et les formats scalaires invalides. Collez votre YAML directement — pas de téléversement de fichier, pas d'inscription, et rien ne quitte votre navigateur.
Validateur YAML
Validez tout document YAML selon la spécification YAML 1.2 - détecte les erreurs de syntaxe liées aux commentaires, les problèmes d'indentation et les clés dupliquées avec des numéros de ligne précis.
Détecter les clés dupliquées dans les fichiers annotés
Quand les développeurs commentent une paire clé-valeur puis ajoutent un remplacement en dessous, les clés dupliquées sont un résultat courant. Par exemple : commenter `timeout: 30` puis ajouter `timeout: 60` en dessous laisse la version commentée inactive — mais si le commentaire est retiré accidentellement ou si le fichier est traité par un outil qui supprime les commentaires, le duplicata devient actif et la valeur inférieure gagne silencieusement (ou provoque une erreur, selon le parseur). Le détecteur de clés dupliquées YAML les détecte avant qu'ils ne causent des problèmes.
Convertir entre formats avec commentaires intacts
Si vous convertissez du JSON en YAML avec le convertisseur JSON vers YAML, notez que la sortie ne contiendra pas de commentaires — JSON n'a pas de syntaxe de commentaires, donc il n'y a aucun commentaire à reporter. Tout commentaire de documentation souhaité dans la sortie YAML doit être ajouté manuellement après conversion. De même, l'outil de fusion YAML peut affecter le placement des commentaires dans les fichiers fusionnés selon la manière dont la fusion est effectuée.
Comparer les configs YAML avant et après édition
Lors de la revue de changements dans des configurations YAML commentées — particulièrement dans les pull requests — le surligneur de diff pour configs JSON/YAML fait ressortir les changements de valeur significatifs séparément des éditions de commentaires uniquement. Cela accélère la revue de code et réduit le risque d'approuver un changement de valeur accidentel noyé dans un diff rempli de mises à jour de commentaires.
Key takeaways
- YAML utilise un seul caractère de commentaire : `#`. Tout ce qui va de `#` à la fin de la ligne est un commentaire.
- Les commentaires en ligne exigent un espace avant `#` - écrire `value# comment` sans l'espace est une erreur de syntaxe ou produit une valeur inattendue.
- YAML n'a pas de syntaxe de commentaire de bloc - commentez plusieurs lignes en préfixant chacune individuellement avec `#`.
- Un `#` dans les chaînes quotées et les scalaires de bloc est toujours un caractère littéral, jamais un commentaire.
- Les commentaires sont invisibles pour les parseurs - ils sont ignorés au chargement et ne peuvent pas être relus par PyYAML, js-yaml ou toute bibliothèque standard.
- Utilisez le suppresseur de commentaires YAML pour supprimer les commentaires avant de transmettre du YAML à des API ou outils de déploiement.
- Validez toujours avec le validateur YAML après avoir ajouté des commentaires en ligne pour détecter les bugs silencieux de troncature de valeurs.