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.