Earlier in my programming days, my go-to example domain would have been foo.com. Well, not always. If we had any inside jokes on the team, I might put something clever in there for fun.
On the Cloud Foundry backend team, one of our current inside jokes includes a picture of Bob Ross in the free space on one of our CI boards. So maybe in that case, if I needed a fake URL for a test, I would have gone with bobross.com or paintingclouds.com, just for fun.
The Importance of Using Example Domains
I think it was Ken Mayer who taught me that example.com is meant to be used in documentation and tests. example.com isn’t just some domain that some private party uses for the greater good. The Internet Engineering Task Force published RFC2606, which says that example.{com,net,org} are reserved exclusively for documentation.
Why would you care about that? Why shouldn’t you go ahead and use chumbawamba.com in the tests you write while rocking out to Tubthumping? RFC2606 explains:
“Test and experimental software can escape and end up being run against the global operational DNS. Even examples used ‘only’ in documentation can end up being coded and released or cause conflicts due to later real use and the possible acquisition of intellectual property rights in such ‘example’ names.”
Besides that, example.com carries no connotations. It is effectively a metasyntactic variable like foo and bar. example.com tells the reader that it’s a domain just for the sake of a domain. There is nothing special about it.
Example IP Addresses for Documentation
Not only do we have example.com for example domains, we also have RFC5737, which describes the example IP addresses to use in documentation.
The blocks 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2), and 203.0.113.0/24 (TEST-NET-3) are provided for use in documentation.
I know I’ve been very guilty of using IP addresses like 1.2.3.4 or 192.168.1.1 when I write example IP addresses. I had never considered that I might inadvertently write an example that does Something Bad™ when copied and pasted because I picked an IP address that maps to a real, live network.
If someone mindlessly copies and pastes echo "Hi!" | nc 192.168.0.1 8000, it probably won’t do any damage. But on the wrong network, nmap 192.168.0.0/16 might actually get its operator in trouble, so we should write nmap 192.0.2.0/24 as an example that’s guaranteed to be harmless. And savvy readers will understand that it’s an IP or domain meant just for the sake of example, no strings attached.
Make a Difference in Open Source Projects
For me, it’s an easy choice now. Use example.com for example domain names — if I need multiple domain names, bobross.example.com is perfectly acceptable. And start with 192.0.2.1 for example IP addresses (192 is easy to remember from 192.168.0.0/24 being in rote memory, and then I just have to remember 0.2 after that).
I’ll be careful about example domains and IPs in the future, but I’m not sure that I’ll spend the time to change existing Cloud Foundry test code that uses nonstandard examples. If you’ve wanted to contribute to an open source project but you’ve never known where to start, I would welcome you to make a pull request fixing nonstandard examples in any of our repositories on GitHub or to any other open source project. I can tell you from firsthand experience that it feels great to say you’ve contributed to an open source project — so what are you waiting for?
