diff --git a/FALSEHOODS.md b/FALSEHOODS.md new file mode 100644 index 000000000..6c3e6c865 --- /dev/null +++ b/FALSEHOODS.md @@ -0,0 +1,120 @@ +# Falsehoods Programmers Believe About Phone Numbers + +... and tips on how to use libphonenumber. + +Given how ubiquitous phone numbers are and how long they've been around, it's +surprising how many false assumptions programmers continue to make about them. + +1. **Phone numbers that are valid today will always be valid. Phone numbers of + a certain type today (e.g., mobile) will never be reassigned to another + type.** + + A phone number which connects today may be disconnected tomorrow. A number + which is free to call today may cost money to call tomorrow. The phone + company may decide to expand the range of available phone numbers by + inserting a digit into an existing number. + + **Tip:** Don’t store properties for a phone number such as validity or + type. Check this information again from the library when you need it. + +1. **A phone number uniquely identifies an individual** + + It wasn't even that long ago that mobile phones didn't exist, and it was + common for an entire household to share one fixed-line telephone number. In + some parts of the world, this is still true, and relatives (or even friends) + share a single phone number. + +1. **An individual has only one phone number** + + Obviously, this isn't necessarily true. + +1. **Phone numbers cannot be re-used** + + Old phone numbers are recycled and get reassigned to other people. + +1. **Each country calling code corresponds to exactly one country** + + The USA, Canada, and several Caribbean islands share the country calling + code +1. Russia and Kazakhstan share +7. These are not the only examples! + +1. **Each country has only one country calling code** + + As of this present moment (in Mar. 2016), phones in the disputed territory + and partially recognised state of Kosovo may be reached by dialing the + country calling code for Serbia (+381), Slovenia (+386), or Monaco (+377), + depending on where and when one obtained the number. + + **Tip:** Use the phone widget to encourage users to enter their phone number + in an international format such that we can understand it. + +1. **A phone number is dialable from anywhere** + + Some numbers can only be dialed within the country. Some can only be dialled + from within a subset of countries, such as the international 00800 numbers. + Some may be dialable only if the caller is a subscriber to a particular + telecom company. + +1. **There are only two ways to dial a phone number: domestically and from + overseas** + + Some numbers may need different prefixes depending on: the carrier you are + using; what device you are dialling from/to; whether you are inside or + outside a particular geographical region. + + Examples: + * In Brazil, to dial numbers internally but across a certain geographical + boundary, a carrier code must be explicitly dialed to say which carrier + you will use to pay for the call. + * In Nepal, the leading zero in national format is omitted depending on + whether the originating phone is mobile or fixed-line. + * In New Zealand, you need to dial the area-code (e.g. 03) even if the + number is within the same area-code region as you are, unless it is + "close" (something approximating city/district boundaries), in which + case it shouldn’t be dialled. + + **Tip:** Use formatForMobileDialling to get the number a user should + actually dial on their mobile phone. + +1. **To make a number dialable, you only need to change the prefix** + + In Argentina, to dial a mobile number domestically, the digits "15" need to + be inserted *after* the area code but *before* the local number, and the "9" + after the country code (54) needs to be removed. This transforms +54 9 2982 + 123456 into 02982 15 123456. + +1. **No prefix of a valid phone number can be a valid phone number** + + In some countries, it's possible to connect to a different endpoint by + dialing more digits after a number. So "12345678" may not reach the same + person as dialing "123456". + +1. **An invalid number will not reach an endpoint** + + In some countries, or on some phones, extra digits are thrown away. Hence, + 1-800-MICROSOFT is an invalid number - but it still connects to Microsoft, + since any later digits are ignored. Numbers such as "911" can be reached by + dialling "911 123" in some countries: but not in others. + + In other countries, invalid numbers may be "fixed" by a carrier, e.g., + adding a mobile token if they know it is a mobile number, such that it + connects. + +1. **All valid phone numbers follow the ITU specifications** + + ITU says things like "national numbers can not be longer than sixteen + digits" but valid numbers in Germany have been assigned that are longer than + this. + +1. **All valid phone numbers belong to a country** + + There are many "country calling codes" issued to non-geographical entities, + such as "800" or satellite services. + +1. **Phone numbers contain only digits** + + In Israel, certain advertising numbers start with a `*`. + +1. **Phone numbers are always written in ASCII** + + In Egypt, it is common for phone numbers to be written in native digits. +