How to Add Comments in a YAML File [Tutorial]

YAML (YAML Ain’t Markup Language), sometimes also referred to as Yet Another Markup Language, is a popular data serialization format that’s specifically designed to be human-readable. It’s a superset of the terser JSON language. YAML adds additional convenience features that make it easier to author and read configuration files.

Comments are one such YAML-specific capability. Writing comments into your files allows you to document your intentions, explain why certain values have been set, and provide links to any relevant reference material. Here’s how to use them.

We will cover:

1. How to add comments to YAML
2. When to use YAML comments
3. Best practices

Comments in YAML files are denoted by a # character. The YAML parser will ignore anything that follows the # character in your lines, allowing you to leave messages that only other humans will see.

1. Making single-line YAML comments

To comment out an entire YAML line, place the # character at the start of the line, then write your message:

The parser ignores the entire line—your human readers will see your message but apps that read the file will ignore it.

2. Making inline YAML comments

Sometimes comments are short enough that they don’t need their own dedicated line. You can insert inline comments into YAML files by simply placing the # character at the end of a line, then writing your message:

Now the parser will still interpret the replicas: 3 statement but won’t see the comment after the # character. This is a good way to describe the context surrounding specific lines, without breaking up the structure of your file.

3. Making block YAML comments

Block (multi-line) comments are a syntax feature found in many programming languages. They allow you to write several comment lines inside a single block, without having to specifically denote each individual line as a comment.

Unfortunately, YAML doesn’t support block comments. To write a multi-line comment, you must prefix every line with the # character:

In this YAML file, the author has provided a long block comment that spans multiple lines. It’s imperative that you remember to prefix every line with the # character to ensure they’re all treated as a comment.

Text editors can usually insert YAML block comments for you. There are two common methods:

1. Most editors will automatically insert a new # prefix when you press the enter key while a commented line is selected. This creates another commented line, continuing the block.
2. You can select a set of lines and activate your editor’s “comment” action, via a keyboard shortcut (often Ctrl+/), the command palette, or the toolbar. This will prefix each of the selected lines with the # prefix for you.

Either of these methods will allow you to create YAML block comments without the risk of accidentally leaving a line unprefixed. If you do forget to include the # character, parsing your YAML file will fail because the interpreter won’t understand your comment’s content.

YAML comments should be used whenever you need to document why you’ve chosen a specific field or value. They can provide invaluable context that helps prevent mistakes when future collaborators edit the file.

If you don’t add comments to unusual lines, it’s possible that others will misinterpret your intentions or unintentionally remove a value that’s required by your application. Simple misconfigurations like this could ultimately cause security breaches and deployment failures.

Using comments to temporarily remove YAML sections

Comments aren’t just for documentation. You can also use them as a mechanism for temporarily disabling parts of a YAML file, without having to entirely delete the relevant section. Commenting it out instead means you can immediately reactivate the original configuration by simply uncommenting the affected lines.

This strategy is invaluable when working with config files that aren’t version controlled as part of a source repository. If your YAML file is version-controlled, you can still use this strategy, but it might be redundant. The versioning means you can simply delete the block, commit the change, and then revert to the previous commit if you need to restore the original version of the file.

Using comments to add file authorship and licensing details

Adding authorship and licensing details to the top of your files is another good use of comments. This makes it clear who wrote the content, as well as the legal restrictions that apply to its use:

We’ve seen that YAML comments are simple to write but there are still some best practices worth following in order to apply them effectively. Here are a few tips to ensure your comments are as useful as possible:

• Break long comments into multi-line comments. Most developers keep code to a maximum line width of 80 characters. The same should apply to your comments to ensure your file remains easy to read. Break long comments into multi-line block sections that allow you to use paragraphs within your message.
• Be consistent in your comment format. Comments affect the readability of your source files. Poorly formatted comments can make it harder to understand the file’s structure at a glance. When using inline comments, try to align them so each comment within a section starts at the same column position in the file. Avoid mixing inline and line comments within a single section.
• Use inline comments for remarks. Inline comments are usually best reserved for short remarks, notes, annotations, and hints. They’re easily ignored as you scan through the file’s main content.
• Use line and block comments for longer documentation. Line comments are part of the flow of the file; you naturally read them as you scroll down. They’re less likely to be overlooked and they provide more space to write important documentation.
• Comment anything that needs to be explained to a future editor. Comments are a frontline defense against misconfiguration. Explaining the reasoning that went into a YAML field or value—such as the assumptions, application requirements, and workarounds that applied—is a best practice technique whenever you author YAML files (or any other kind of markup or code).

Keeping these pointers in mind will ensure your YAML files are annotated with salient comments that aid future maintainability.

YAML supports comments that allow you to add documentation to your files. Because YAML is often used to express complex IaC configurations, as well as general DevOps rules and policies, it’s essential that everyone understands the purpose of each field including why a particular value has been used. Writing concise comments supports comprehension and eliminates ambiguity.

YAML is an important language that finds its uses almost everywhere where writing configuration is required. Kubernetes, Ansible, docker-compose, and other tools are excellent examples.

Then you can use Spacelift to mix and match OpenTofu, Terraform, Pulumi, AWS CloudFormation, Kubernetes, and Ansible Stacks and have them talk to one another. For example, you can set up Terraform Stacks to provision the required infrastructure (like an ECS/EKS cluster with all its dependencies) and then deploy the following via a Kubernetes Stack. Check it out for free by creating a trial account.