YAML Comments

A comment in YAML is a line or part of a line that YAML parsers completely ignore. Comments are written by humans, for humans. They explain what a setting does, why a value was chosen, or what a section of the file controls. Comments do not affect how the YAML file works — they are purely informational.

How to Write a Comment in YAML

Every comment in YAML starts with the hash symbol #. Everything after # on that line becomes a comment.

# This is a full-line comment
name: Alice   # This is an inline comment

The first line is a full-line comment. The second line has a value followed by an inline comment. The parser reads name: Alice and ignores the part after #.

Comment Rules

• Comments start with #
• A space before # is recommended when writing inline comments
• Comments can appear on their own line or at the end of a line with data
• YAML does not support multi-line comment blocks (no /* */ like in other languages)
• A # inside a quoted string is NOT a comment — it is treated as a literal character

Comment Types Diagram

+--------------------------------------------------+
|  Type               |  Example                  |
+--------------------------------------------------+
|  Full-line comment  |  # Server configuration   |
|  Inline comment     |  port: 8080  # Default    |
|  NOT a comment      |  text: "Use #hashtag"     |
+--------------------------------------------------+

Full-Line Comment Examples

# Application Settings
app_name: MyShop
version: 2.0

# Database Configuration
db_host: localhost
db_port: 5432
db_name: shopdb

Full-line comments act as section headers. They help anyone reading the file understand what the next group of settings controls.

Inline Comment Examples

port: 8080           # HTTP port, change to 443 for HTTPS
max_retries: 3       # Number of reconnect attempts
timeout: 30          # Seconds before request times out
debug: false         # Set to true only in development

Inline comments sit to the right of a value. Always leave at least one space before the # to keep things readable.

Hash Symbol Inside a Quoted String

When a hash symbol appears inside single or double quotes, it is treated as a regular character, not a comment.

message: "Use #hashtag to tag your posts"
color_code: '#FF5733'

Both values are stored exactly as written, including the # character.

Commenting Out a Setting

A common practice is to comment out a line by adding # at the beginning. This disables that setting without deleting it. It remains visible for reference and can be re-enabled by removing the #.

server:
  host: localhost
  port: 8080
  # ssl_cert: /etc/ssl/cert.pem   # Disabled – SSL not yet configured
  # ssl_key: /etc/ssl/key.pem

The SSL settings are preserved but inactive. This is useful during development when a feature is not ready yet.

Real-World Example – Commented Docker Compose File

# Docker Compose Configuration for MyApp
# Version: 3.9

version: "3.9"

services:
  # Web application container
  web:
    image: nginx:latest
    ports:
      - "80:80"     # Map host port 80 to container port 80
      - "443:443"   # HTTPS port mapping
    volumes:
      - ./html:/usr/share/nginx/html   # Mount website files

  # Database container
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret   # Change this in production!
      POSTGRES_DB: mydb
    # ports:
    #   - "5432:5432"   # Uncomment to expose DB to host

This example shows how comments improve the readability of a real configuration file. The commented-out ports section shows a useful option that is currently disabled.

Good Commenting Practices

What Comments Cannot Do

• Comments cannot span multiple lines with a block syntax — each line needs its own #
• Comments are not preserved by all YAML parsers — some parsers strip comments when reading and rewriting files
• Comments cannot appear inside flow-style mappings or sequences in some parsers

Multi-Line Comments – Write Each Line Separately

# This is a multi-line comment in YAML.
# Each line must start with its own hash symbol.
# There is no block comment syntax in YAML.

Summary

• Comments start with # and are completely ignored by parsers
• Full-line comments occupy an entire line
• Inline comments appear at the end of a data line after a space and #
• A # inside quotes is a literal character, not a comment
• Use comments to document settings, explain values, and disable options temporarily
• YAML has no block comment syntax — each comment line needs its own #