Use care in examples and placeholders

Multi-color letter magnets strewn across a table.

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.

Ben formerly led open source messaging at Docker and was the Fedora Program Manager. He is the author of Program Management for Open Source Projects. Ben is an Open Organization Ambassador and frequent conference speaker. His personal website is Funnel Fiasco.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.