YAML – Comments

YAML - Comments

Comments are essential for annotating your YAML files, making them more understandable for yourself and others. YAML supports single-line comments.

Syntax

A comment in YAML starts with a hash symbol (#) and extends to the end of the line. Anything following the # on that line is ignored by the YAML parser.

# This is a single-line comment.

Comments can appear on their own line or at the end of a line containing YAML data, provided they are separated from the data by whitespace:

key: value # This comment describes the key-value pair.

# This comment is on its own line, perhaps explaining the block below.
another_key: another_value

YAML does not support multi-line block comments (like /* ... */ in some languages). To create a multi-line comment, you simply start each line with a #:

# This
# is a multi-line
# comment block.

Key Characteristics of Comments

• Ignored during parsing: Commented-out sections are completely skipped when the YAML file is processed.
• Enhance readability: Comments help clarify the purpose of data, configuration settings, or complex structures.
• Placement: Comments must not appear inside unquoted plain scalars. If a # appears within a plain scalar, it’s treated as part of the string.
• No escape for # in plain scalars: Within unquoted multi-line plain scalars, a # character will typically terminate the scalar or be interpreted as content if not at the beginning of a line in a way that denotes a comment. For literal inclusion of # where it might be ambiguous, use quoted scalars.
• Inside quoted scalars ("..." or '...'), the # symbol is treated as a literal character, not a comment delimiter.

Comments within Collections

You can place comments within sequences (lists) and mappings (dictionaries) to explain specific items or sections:

servers:
  - ip: 192.168.1.100 # Main application server
    role: app
  - ip: 192.168.1.101 # Database server
    role: db
# - ip: 192.168.1.102 # Temporarily disabled web server
#   role: web

config:
  timeout: 30 # Timeout in seconds
  retries: 3  # Number of retries for failed connections

Commenting Out Blocks of Code

Most modern text editors and IDEs (like VS Code, IntelliJ IDEA, Sublime Text, etc.) provide shortcuts to comment or uncomment selected lines or blocks of YAML code. A common shortcut is Ctrl+/ (Windows/Linux) or Cmd+/ (macOS). This typically prepends # to each selected line.

This feature is very useful for temporarily disabling sections of your YAML file for testing or debugging purposes.

Best Practices for Comments

• Be clear and concise.
• Explain the ‘why’, not just the ‘what’, if the data isn’t self-explanatory.
• Keep comments up-to-date with changes in the YAML data.
• Use comments to mark sections, explain complex configurations, or note down TODOs.