YAML Best Practices for Clean Config Files
Most YAML advice is about avoiding errors. This one's slightly different — it's about writing YAML that's genuinely pleasant for the next person (very possibly you, in six months) to open and understand.
Pick 2 spaces and never deviate
Whichever indent size you choose, the value of consistency is bigger than the value of the specific number. Set your editor to enforce it automatically for YAML files rather than relying on memory.
Quote anything ambiguous, even if it isn't strictly required
Version numbers, country codes, time values, anything that starts with a special character — quote them even when the parser would technically accept them unquoted. It costs nothing and removes an entire category of "why did this get misread" bugs, including the boolean and Norway problems covered in our data types guide.
Use comments to explain "why," not "what"
A comment like # retry count above retries: 3 doesn't add much — the key name already says that. A comment like # bumped from 3 to 5 after the payments API started timing out under load is genuinely useful, because it tells a future reader something the file can't say on its own.
Keep nesting as shallow as the tool allows
Some nesting is unavoidable — Kubernetes manifests, for instance, are just deeply nested by nature. But where you have a choice, flatter structures are easier to scan and less prone to the indentation mistakes that come with deep nesting.
Group related keys together, and keep a consistent order
If every service block in a Docker Compose file lists image, then ports, then environment in the same order, a reader builds a mental model fast. Randomly ordered keys make every new file feel like starting from scratch.
Run it through a formatter before committing
A quick pass through the formatter before a commit catches inconsistent indentation and confirms the file is genuinely valid — a cheap habit that saves someone else a confusing pull request comment later.
None of this is enforced by YAML itself — that's exactly why it's called "best practice" rather than "syntax rule." But teams that adopt even three or four of these habits tend to spend noticeably less time debugging config files.