Use care in examples and placeholders
Last month, Maciej Pocwierz shared the story of a huge AWS bill caused by an unfortunate bucket name. A lot of things had to go wrong for the stars to line up right, but they did. While the bill could reasonably be attributed to unfortunate design decisions on Amazon’s part, there’s a lesson here for all of us: docs examples and config file placeholders matter.
For domains, “example” is the right choice. RFC 6761 describes example and other special-use domains. You can safely use this in documentation, sample code, configuration files, and so on without worry. (Unless your software does something destructive when it can’t reach service. In that case, worry.) But not everything you might need a placeholder for is a domain. In that case, if you can use invalid strings, that’s a good way to keep things from going sideways. For example S3 bucket names can’t include em dashes, so this—is—always—safe.
Usually, you want to ship with usable (and useful) defaults. But placeholder configs for services that the user will interact with should be intentionally broken. This helps protect anyone who might be on the receiving end of a spike in traffic (or billing!). But it also protects your users since pointing to a non-reserved domain presents the risk of the domain changing hands down the line.
This post’s featured photo by Towfiqu barbhuiya on Unsplash.
