Commentaires YAML : commenter du YAML et le mettre en commentaire
Commentaires YAML
Commentaires YAML : syntaxe, règles en ligne et astuces pour les blocs | We.Inc
Comment commenter en YAML : la syntaxe #, la règle de l'espace pour les commentaires en ligne, pourquoi il n'existe pas de commentaire de bloc, et un outil qui commente ou rétablit plusieurs lignes à la fois.
Un commentaire YAML commence par un dièse (#) et se poursuit jusqu'à la fin de la ligne. Il peut occuper sa propre ligne ou suivre une valeur, à condition qu'un espace le sépare de la valeur. YAML n'a pas de syntaxe de commentaire de bloc : pour mettre plusieurs lignes en commentaire, il faut placer un # au début de chacune.
Où le # ouvre un commentaire en YAML, et où il ne le fait pas
Ligne
Le # est-il un commentaire ?
Pourquoi
Oui
Il commence la ligne
port: 5432 # default
Oui
Un espace précède le #
url: https://x.example/#top
Non
Aucun espace avant le #, il fait donc partie de la valeur
color: "#4F98FB"
Non
À l'intérieur d'une chaîne entre guillemets
tag: #blue
Oui
La valeur est vide (null) et le reste est un commentaire
Les commentaires sont la principale raison pour laquelle les équipes préfèrent YAML à JSON pour la configuration, et pourtant leurs règles piègent facilement. Collez un fichier dans l'outil ci-dessous pour mettre en commentaire une plage de lignes ou la rétablir, puis consultez la référence pour les cas où un # devient discrètement une partie de vos données.
Collez votre YAML dans la zone, ou modifiez l'exemple.
Saisissez les numéros de la première et de la dernière ligne à modifier.
Appuyez sur Commenter pour ajouter un # après l'indentation de chaque ligne, ou sur Décommenter pour le retirer.
Recopiez le résultat dans votre fichier. Les lignes vides de la plage restent inchangées.
Alignez le # sur le code qu'il désactive. Des lignes commentées à la même indentation sont bien plus faciles à rétablir ensuite.
Mettez un espace après le # dans vos propres notes. Ce n'est pas obligatoire, mais cela permet de distinguer facilement le code désactivé des remarques.
Mettez entre guillemets toute valeur contenant un # à conserver, comme les couleurs hexadécimales, pour qu'une modification ultérieure ne puisse pas le transformer en commentaire.
N'oubliez pas que la plupart des librairies suppriment les commentaires quand un fichier est chargé puis réenregistré. Ne stockez rien d'important uniquement dans un commentaire que des outils réécrivent.
Questions fréquentes
YAML a-t-il des commentaires multilignes ou de bloc ?
Non. La spécification ne définit que des commentaires de ligne commençant par #. Pour désactiver un bloc, préfixez chaque ligne par #. La plupart des éditeurs le font pour une sélection avec un seul raccourci, et l'outil de cette page le fait pour n'importe quelle plage de lignes.
Pourquoi mon commentaire est-il devenu une partie de la valeur ?
Un # n'ouvre un commentaire que s'il est précédé d'un espace. Dans url: https://site.example/#faq, le # suit une barre oblique, il reste donc dans la chaîne. Ajoutez un espace avant le # si vous vouliez un commentaire.
Les commentaires sont-ils conservés lors d'une conversion de YAML en JSON ?
Non. Les commentaires sont un détail de présentation, pas des données, et JSON n'a aucun endroit où les mettre. La RFC 9512 note que les commentaires sont supprimés quand du YAML est sérialisé en JSON.
Puis-je commenter à l'intérieur d'un bloc scalaire ?
Non. Dans un bloc | ou >, une ligne qui commence par # est du texte ordinaire et fait partie de la chaîne. Les commentaires ne fonctionnent qu'en dehors des lignes de contenu du bloc.
Quel est le raccourci pour commenter du YAML dans un éditeur ?
Il dépend de l'éditeur, pas de YAML. Dans Visual Studio Code, la commande Toggle Line Comment correspond à Ctrl+/ sous Windows et Linux et à Cmd+/ sous macOS ; les autres éditeurs définissent leurs propres touches.
Les commentaires en ligne et la règle de l'espace
La spécification YAML indique que les commentaires doivent être séparés des autres éléments par un espace. Cette seule règle explique presque toutes les surprises : un # collé au texte qui le précède est une donnée, et un # après un espace marque le début d'une note.
Une tabulation compte aussi comme espace ici, mais comme les tabulations sont interdites pour l'indentation, il est plus simple d'utiliser des espaces partout.
Bien documenter un fichier de configuration
Écrivez des commentaires qui expliquent pourquoi une valeur est définie, pas ce que le nom de la clé dit déjà. Une ligne comme # 5 nouvelles tentatives car l'API de paiement expire sous la charge évite à la personne suivante de fouiller l'historique.
Placez en haut un court commentaire d'en-tête indiquant quel programme lit le fichier et où ses options complètes sont documentées.
Les modèles de commentaires que vous utiliserez
Commentaires sur toute une ligne et en ligne
Un commentaire sur toute une ligne explique une section ; un commentaire en ligne demande au moins un espace avant le #.
Désactiver temporairement un bloc
Chaque ligne du service désactivé porte son propre #, gardé à l'indentation d'origine pour pouvoir le rétablir proprement.
Mettre des lignes YAML en commentaire
Collez du YAML, choisissez une plage de lignes et basculez ces lignes entre actives et commentées. L'indentation est conservée, pour que la structure reste lisible.