YAML Comments Guide

What are YAML Comments?

Comments in YAML are used to add explanatory notes or temporarily disable code without deleting it. They are ignored by YAML parsers and are purely for human readers.

Key Point

YAML comments start with the hash symbol (#) and continue to the end of the line.

Comment Syntax

Single-Line Comments

Use the hash symbol (#) to start a comment:

# This is a single-line comment
name: John Doe  # Inline comment
age: 30

Inline Comments

Comments can appear at the end of a line:

database:
  host: localhost  # Development environment
  port: 5432       # PostgreSQL default port
  name: myapp      # Application database

Multi-Line Comments

YAML doesn't have native multi-line comment syntax, but you can use multiple single-line comments:

# Database Configuration
# This section defines the database connection settings
# Make sure to update these values for production
database:
  host: localhost
  port: 5432

Common Use Cases

1. Document Configuration

# Application Configuration
# Version: 2.0
# Last modified: 2024-11-16

app:
  name: MyApp
  version: 2.0.1
  
# Server settings
server:
  host: 0.0.0.0  # Listen on all interfaces
  port: 8080     # HTTP port

2. Temporarily Disable Code

features:
  authentication: true
  # logging: true      # Temporarily disabled
  notifications: true
  # analytics: false   # Disabled for testing

3. Add Warnings and Notes

# WARNING: Do not modify these values in production!
security:
  # IMPORTANT: Keep this secret safe
  api_key: "your-secret-key"
  
  # TODO: Implement rate limiting
  rate_limit: 1000

4. Section Headers

# ================================
# Database Configuration
# ================================

database:
  primary:
    host: db1.example.com
    port: 5432
  
# ================================
# Cache Configuration
# ================================

cache:
  redis:
    host: redis.example.com
    port: 6379

Best Practices

✓ Do: Be Clear and Concise

# Maximum number of concurrent connections
max_connections: 100

✓ Do: Use Comments to Explain Why

# Use 2048 instead of 1024 for better security
# as per security audit recommendation
encryption_key_size: 2048

✗ Don't: State the Obvious

# Set name to John
name: John  # This is redundant

✗ Don't: Over-Comment

# Database host
host: localhost  # This is the host
# Database port
port: 5432       # This is the port

Special Considerations

Hash Symbol in Strings

If you need to use # in a string value, make sure to quote it:

# Correct - quoted string
message: "Use # for comments"
tag: "#programming"

# Incorrect - this will be interpreted as a comment
# message: Use # for comments  # WRONG!

Comments in Multi-Line Strings

Comments cannot be used within multi-line strings:

description: |
  This is a multi-line string.
  # This is NOT a comment, it's part of the string!
  The text continues here.

Real-World Examples

Docker Compose Configuration

# Docker Compose configuration for MyApp
version: '3.8'

services:
  # Web application service
  web:
    image: nginx:latest
    ports:
      - "80:80"      # HTTP
      - "443:443"    # HTTPS
    
  # Database service
  db:
    image: postgres:14
    environment:
      # Database credentials (use secrets in production!)
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      # Persist database data
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:  # Named volume for database persistence

GitHub Actions Workflow

# CI/CD Pipeline
name: Build and Test

on:
  push:
    branches:
      - main          # Run on main branch
      - develop       # Run on develop branch
  pull_request:       # Run on pull requests

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      # Checkout code
      - uses: actions/checkout@v2
      
      # Setup Node.js environment
      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '18'  # LTS version
      
      # Install dependencies and run tests
      - run: npm ci
      - run: npm test