A quick YAML refresher, since I forget so easily

YAML example

---
# A pet record
nick: Cat
  name: Cat McCattums
  type: Felis catus
  homed: True
  insured: True
  foods:
    - Fish
    - Water
    - Nip
    # This is an attempt at humour
    - Sandals
  languages:
    cat: Fluent
    english: Own name recognition only
    bird: Spoken only
  medical: |
    Basic vaccines given
    Nutrition verified
    Health check dated Oct 27
nick: Dog
    name: Doggo YuDoggem # seeing a pattern here eh
    type: Canis familiaris

Use comments generously in your YAML

A YAML comment looks like:

# I'm a comment

More than one line is exactly the same pattern.

# Really good
# readable comment
# is here

Comments mitigate technical debt

This is a general comment, not just intended for YAML.

Comments are useful and helpful af.

For example, when configuring a redirect using YAML, I can tell future Manil why he made that configuration in the first place. This is massively helpful for cleanup. Cleanup is made much easier when I don't have to dig around to find out I why did something, long after the context of the specific incident has passed from memory.

The comment could tell me I added a few lines:

# to make demo work 
# without Some Service 
# that isn't currently available

And future me would know, "Well, that was obviously meant to be temporary, because Some Service is up now."

Boom, delete line. No more thoughts given.

The most useful thing is that anyone else could read that and make a similar decision. Manil is that much less likely to get a message asking about the redirect, even if git blame showed that he committed that line change.

Meta

Sources

• https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html