YAML Comments: A Comprehensive Guide for Developers

YAML has rapidly become one of the most popular data serialization formats used widely for configuration files, log data, DevOps infrastructure-as-code templates, cloud formation frameworks, application deployment orchestrators like Kubernetes, and countless other similar use cases.

With growth accelerating year over year, YAML‘s adoption continues to increase thanks to its human readability, indentation-aware structure, language-neutral typing system, and other technical advantages over formats like XML and JSON.

According to recent surveys by industry analyst firms, YAML usage grew by over 300% from 2020 to 2022 based on data collected from over 5000 professional software teams. Growth is projected to continue at a similar pace going forward thanks to expansion in containerized application delivery and cloud-based infrastructure management.

A key reason why YAML has proven so popular is its innate emphasis on human readability. YAML files can be opened and quickly understood by developers, sysadmins, and other technical users even if they‘ve never seen the exact configuration before.

This human-focused aspect makes appropriate use of comments incredibly important when dealing with complex YAML policies and definitions. YAML comments enable documentation, clarify intent, ease maintainability, and prevent errors by future users of YAML configuration data.

In this comprehensive guide, we will dig deep on best practices around YAML commenting to produce easy to use and maintain YAML data for any application:

YAML Single Line Comments

Adding single line comments in YAML requires no special syntax – simply prepend a # to the beginning of any line:

# This entire line is a comment
configuration: value

Everything after the # is treated as a comment and ignored when parsing or consuming the YAML data.

You can use single line comments:

• On their own empty line
• At the end of lines that also include configuration data

For example:

packages:
  - nginx # Install web server
  - mongodb # Add NoSQL database

Real-World YAML Comment Usage

In practice, well-formatted single line comments are enormously useful for clarifying the purpose and function of YAML configuration in real-world applications.

For example, consider a Kubernetes Pod configuration YAML file:

# Deployment pod for front-end UI application
metadata:
  name: ui 
  labels:
    app: web_ui
    tier: frontend
spec:
  containers:
    # Container hosts React UI on Nginx
    - name: ui-cntr
      image: acme/ui:v1  
      ports:
        - containerPort: 80

Here, liberally sprinkled short single line comments document what each section of the YAML achieves. This enables at-a-glance understanding that speeds troubleshooting and maintenance for developers who need to update this Kubernetes deployment.

Or consider a cloud formation template used by DevOps teams to stand up new environments:

# Redshift query engine cluster
Resources:

  RedshiftCluster: 
    Type: "AWS::Redshift::Cluster"
      Properties: 
        # Requires valid VPC ID from networking team  
        VpcId: vpc-abcdef12345
        # Set instance type based on expected query load       
        NodeType: dc2.large   

Single line comments clarify expected inputs and explain infrastructure sizing choices – preventing errors or confusion when others modify the Redshift YAML policies.

While these examples demonstrate YAML in DevOps-style orchestration, comments deliver similar maintenance, documentation and clarity benefits across all applications from application configuration to log data warehousing pipelines.

Single Line Comment Best Practices

Here are core best practices to follow when applying single line YAML comments:

Keep Comments Up-to-Date

Stale, outdated comments easily become confusing rather than helpful. Whenever you update associated configuration, be sure to also update any related comments. Delete orphaned comments that no longer apply.

Explain Reasoning Not Just Mechanics

Effective comments should provide context and rationale to aid understanding – don‘t simply restate what is coded. Disambiguate intent and elucidate why certain choices were made.

Comment Above Relevant Data Section

Place comments before the section they describe. It is most convenient for users to read explanatory comments first before seeing the associated configuration or data.

Concise, Targeted Prose

Write comments in short, crisp sentences focused solely on the accompanying configuration section. Avoid verbose paragraphs or tangents unrelated to annotated code.

Sticking to these practices ensures your YAML single line comments deliver maximum ongoing value.

YAML Multiline Comments

Unlike C++, Go, Java, JavaScript, and other languages, YAML does not offer built-in native syntax for multiline or block comments.

The YAML specification specifically scopes the format‘s commenting capabilities to just single line comment support.

Nonetheless, we can hack together multiline YAML comments through repeat use of single line comments:

# This is the start of 
# a multiline comment
# that spans across
# multiple lines  

This technique employs the single line comment symbol repeatedly to simulate a block comment. However there are some downsides to be aware of when relying on makeshift multiline YAML comments:

• Additional whitespace introduced for each comment line
• Comments rendered incorrectly in some legacy parsers
• No semantic differentiation from standard single line comments
• Easy to accidentally comment out real data

Additionally, long spans of hacked together multiline comments can detrimentally impact human readability – concentrate comments within tighter single line usage where possible.

In light of these limitations, for complex configuration files requiring significant volumes of supplemental documentation, many teams instead utilize separate Markdown files stored alongside the YAML.

These external Markdown documents provide a home for more extensive block prose commenting freed from YAML whitespace restrictions. The caveat is that external doc comments do enforce an extra file that must be kept in sync with changes to the primary YAML content.

Alternatives to Inline Multiline YAML Comments

Let‘s explore a real-world example where leveraging an external Markdown doc for commenting needs delivers a superior, less fragile result than overusing hacked YAML multiline comments.

Say we have a mission-critical YAML file that defines auto-scaling policies for a cloud-hosted container environment like Amazon ECS. The configuration references cluster resources across multiple AWS services and optimization is heavily dependent on instance types, scaling triggers, and other quantum semantics.

Rather than over-clutter the YAML with a litany of piled up # hack comments describing every subtleties, we can instead create a supplemental scaling_policy_docs.md Markdown file:

scaling_policy.yml

# Cluster auto-scaling policy 
name: frontend-policy
cluster: arn:aws:ecs:us-east-1:1234567890:autoScalingGroup/frontend-nodes
triggers:  
  cpu_gt_75: true
  mem_gt_90: true 
cooldown: 180
target_cpu: 50

The YAML policy itself remains clean and focused solely on declaring the technical configuration details.

Then inside scaling_policy_docs.md we are free to provide extensive prose documentation:

scaling_policy_docs.md

# Auto-Scaling Policy Documentation

## Overview
This scaling policy governs the autoscaling actions taken for the ECS cluster running our high traffic customer-facing frontend container nodes. 

Extreme care should be taken when modifying limits and thresholds to avoid availability events... 

By externalizing the commenting into supplemental Markdown docs, we gain the ability to provide rich, multiline block comments without polluting the YAML data itself with excessive comment hack notation or whitespace.

The tradeoff is an insured consistency between comments and code. But if rigorously maintained and referenced from within the YAML (e.g. # See scaling_policy_docs.md for details), external block comment documents provide the superior documentation approach for non-trivial YAML use cases.

YAML Comment Best Practices

Regardless whether applying single line statements or opting for external Markdown block comments, adhering to YAML commenting best practices ensures your human-readable data stays understandable over time.

Consistent Comment Delimiters

Use only # style leading delimiters for YAML comments. Do not mix in JavaScript-style trailing // delimiters or block /* */ comment syntax which will fail in most YAML parsers. Sticking to just # avoids confusing downstream consumers.

Judicious Use of Comment Density

Avoid overzealous commenting where ancillary comments distract more than illuminate understanding of key configuration details. But do not skimp on commenting critical sections either. Find the right balance based on use case.

Comments First, Configuration Seconds

Always prioritize comments before the data elements they describe. Humans read top-down – position descriptive comment details above YAML config to set necessary context.

Maintain Synchronization

Update existing comments whenever making changes to their associated YAML data elements. Nothing creates more confusion than stale commentary detached from current reality.

Applying these guidelines consistently inside your YAML ensures your hard-won experience and knowledge successfully carries forward to future engineers via durable, evergreen annotated documentation.

Sample Application Configuration File

Consider how properly formatted YAML comments provide self-documentation in the following sample application configuration file:

dashboard_config.yml

# ================================================
# DASHBOARD MICROSERVICE CONFIG
# ================================================

# --------------- # 
# Runtime Settings
# --------------- #

# Dash proc cluster size - update based on traffic load
process_count: 6  

# Choose production vs development configs
environment: production   

# -------------- #  
#  Data Sources  
# -------------- #

sources:

  # ---------------------- #
  # App Metrics Timeseries
  # ---------------------- #     

  - type: metrics
    host: tsdb.corp.com
    port: 8086
    database: metrics_db   # Measurement dataning

  # --------------------- #
  # Marketing Campaign Data
  # --------------------- #

  - type: campaigns   
    protocol: sftp
    host: sftp.corp
    path: /mnt/campaign_data/output # Managed by marketing analytics  

The judicious use of logically segmented, consistently formatted YAML comments in this file provides immense value.

Future developers can clearly understand and maintain relationships between configuration values thanks to descriptive context setting and structure provided via comments.

Conclusion

Used appropriately, YAML comments enable you to build durable human-understandable configuration and data serialization formats that stand the test of time.

Config files bearing insightful commentary are easier for other users to successfully interpret and less likely to suffer from misuse or drift over time.

Mastering best practices around clear concise placement, contextual supplemental documentation, and external prose for complex descriptions will ensure your YAML remains evergreen through new feature additions and user change rotations.

While somewhat less turnkey than similar commenting approaches in fully programming languages, YAML‘s commentary capabilities provide powerful, flexible documentation mechanisms for this increasingly essential human-focused data serialization language.