add FALSEHOODS.md

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.
+