How to Write Comments in YAML

One of the nicer things about YAML compared to JSON is that you're actually allowed to leave yourself notes. If you've ever wanted to explain why a config value is set to something weird, this is how.

The basic syntax

# This is a full-line comment
name: Aditi Verma  # this is an inline comment
port: 8080          # default is 3000, we override it for staging

Anything after a # is ignored by the parser, whether it's on its own line or trailing after a value. There's no closing symbol needed and no multi-line comment block — every line of a comment needs its own #.

A couple of gotchas

• A # inside a quoted string isn't a comment. message: "price is #1 today" keeps the whole string, because it's inside quotes.
• A # right after a value with no space can misbehave in some parsers. Writing port: 8080 #comment with a space before the hash is the safe habit to build.
• No block comment syntax. If you want to "comment out" ten lines of YAML temporarily, you either prefix each one with #, or move them out of the file — there's no /* ... */ equivalent.

Where comments actually help

The most useful place for a comment is next to any value that looks arbitrary out of context — a magic port number, a retry count, a feature flag that's temporarily on for one environment. Six months later, that comment is the difference between "I remember why this is here" and quietly being afraid to touch it.

Comments are stripped out completely when you format or convert YAML, including in our formatter — they're for humans reading the source, not part of the actual data. If you're going from YAML to JSON, that's expected: JSON has no comment syntax to convert them into, so double check anything important is also written down somewhere else, like a README.

← Format your YAML now