blog: Add 2025-07-20.md

Author: ingydotnet

blog/2025-07-20.md

@@ -0,0 +1,138 @@
+---
+title: YAML Best Practices
+date: 2025-07-20
+draft: false
+authors: [ingydotnet]
+categories: [Summer-of-YS]
+edit: blog/2025-07-20.md
+comments: true
+---
+
+YAML has a [Core Development Team](https://yaml.org/spec/1.2.2/ext/team/) of
+five people that I am a member of.
+
+In May 2024, 4 of us met in Berlin.
+One of the things we did was to write a list of best practices for YAML.
+We came up with a list of 40 or so things that we all agreed on.
+
+Today I'll share some of those with you.
+
+<!-- more -->
+
+
+## Don't quote strings that don't need to be quoted
+
+One of the main points of YAML was to create a format that consisted of more
+data and less syntax.
+
+People tend to quote strings that contain anything they are not sure about,
+instead of learning the rules for when to quote and when to not quote.
+
+Scalar values without quotes are called "plain scalars".
+
+The basic rules for plain scalars are pretty simple:
+
+* They can't start with these characters: `!`, `@`, `#`, `%`, `&`, `*`, `|`,
+  `>`, `,`, `{`, `}`, `[`, `]`, `>`, `?`, `'`, `"`, a backtick or whitespace
+* They can't contain `: ` or ` #` combinations
+* They can't end with whitespace
+
+That's pretty much it.
+
+If you're not sure, don't quote it!
+
+
+## Prefer single quotes over double quotes
+
+For some reason, people tend to use double quotes for strings much more than
+single quotes.
+
+Single and double quoted strings have different semantics in YAML.
+
+Double quoted strings provide a way to escape characters.
+
+Single quoted strings only provide a way to escape a single quote (use 2 single
+quotes to escape a single quote).
+
+Only use double quotes if you need to escape something.
+
+Note: In YS (code mode) double quoted strings also provide a way to interpolate
+variables.
+
+
+## Use JSON's `true`, `false` and `null`
+
+The YAML 1.2 core schema lets you use `TRUE` and `True` variants of `true`.
+Same for `false` and `null`.
+
+Stick to the JSON standard of `true`, `false` and `null`.
+
+For null values in mappings you can also use the empty string (nothing) to
+represent `null`.
+
+```yaml
+a null value: null
+also null:
+don't use: NULL
+```
+
+That can be useful in YS too.
+Print a blank line with:
+
+```
+say: 'one'
+say:        # blank line
+say: 'two'
+```
+
+
+## Non-empty YAML files should end with a newline
+
+There are some edge cases where different YAML parsers will disagree on the
+meaning of a YAML file when it doesn't end with a newline.
+
+It's best to end your YAML files with a newline.
+Most editors can be configured to add a newline at the end of the file.
+
+Do it.
+
+
+## Don't block sequences in mappings
+
+This one is a bit controversial.
+
+When you have a sequence in a mapping, the `- ` essentially counts as
+indentation.
+
+```yaml
+a mapping:
+- a sequence
+```
+
+Many people will indent it like this:
+
+```yaml
+a mapping:
+  - a sequence
+```
+
+You won't be arrested by the YAML police for doing this, but the core team
+prefers the former style.
+
+
+## Use `.yaml` file extensions
+
+We always wished that people would use the `.yaml` file extension for YAML
+files.
+At some point people started using `.yml` extensions and we didn't yell about
+it.
+
+We know that ship has sailed, but we still prefer `.yaml` over `.yml` if you
+are starting something new and have the choice.
+
+
+## 50 Posts!
+
+If you haven't noticed the Summer of YS blog series is over half way done!
+
+Today is the 50th post in the series!!!