Merge style guide from README.md into CONTRIBUTING.md (#1696)

CONTRIBUTING.md

@@ -140,6 +140,29 @@ that you know.
 
 ### Stub file coding style
 
+#### Syntax example
+
+The below is an excerpt from the types for the `datetime` module.
+
+```python
+MAXYEAR = ...  # type: int
+MINYEAR = ...  # type: int
+
+class date(object):
+    def __init__(self, year: int, month: int, day: int) -> None: ...
+    @classmethod
+    def fromtimestamp(cls, timestamp: float) -> date: ...
+    @classmethod
+    def today(cls) -> date: ...
+    @classmethod
+    def fromordinal(cls, ordinal: int) -> date: ...
+    def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ...
+    def ctime(self) -> str: ...
+    def weekday(self) -> int: ...
+```
+
+#### Conventions
+
 Stub files are *like* Python files and you should generally expect them
 to look the same.  Your tools should be able to successfully treat them
 as regular Python files.  However, there are a few important differences
@@ -159,6 +182,21 @@ rule is that they should be as concise as possible.  Specifically:
 * do not use docstrings;
 * for arguments with a type and a default, use spaces around the `=`.
 
+Stub files should only contain information necessary for the type
+checker, and leave out unnecessary detail:
+* for arguments with a default, use `...` instead of the actual
+  default;
+* for arguments that default to `None`, use `Optional[]` explicitly
+  (see below for details);
+* use `float` instead of `Union[int, float]`.
+
+Some further tips for good type hints:
+* avoid invariant collection types (`List`, `Dict`) in argument
+  positions, in favor of covariant types like `Mapping` or `Sequence`;
+* avoid Union return types: https://github.com/python/mypy/issues/1693;
+* in Python 2, whenever possible, use `unicode` if that's the only
+  possible type, and `Text` if it can be either `unicode` or `bytes`.
+
 Imports in stubs are considered private (not part of the exported API)
 unless:
 * they use the form ``from library import name as name`` (sic, using

README.md

@@ -49,51 +49,9 @@ file (i.e., it can be interpreted by Python 3), except all the methods are empty
 Python function annotations ([PEP 3107](https://www.python.org/dev/peps/pep-3107/))
 are used to describe the types the function has.
 
-See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax
-of the stub files.
-
-## Syntax example
-
-The below is an excerpt from the types for the `datetime` module.
-
-```python
-from typing import Union
-
-MAXYEAR = ...  # type: int
-MINYEAR = ...  # type: int
-
-class date(object):
-    def __init__(self, year: int, month: int, day: int) -> None: ...
-    @classmethod
-    def fromtimestamp(cls, timestamp: float) -> date: ...
-    @classmethod
-    def today(cls) -> date: ...
-    @classmethod
-    def fromordinal(cls, ordinal: int) -> date: ...
-    def replace(self, year: int = ..., month: int = ..., day: int = ...) -> date: ...
-    def ctime(self) -> str: ...
-    def weekday(self) -> int: ...
-```
-
-## Conventions
-
-* At the time of this writing, `unicode` arguments, in Python 2 stubs, are
-  interpreted by type-checkers as `Union[bytes, unicode]` (so it means the same
-  as `Text`).
-  Even so, in Python 2, whenever possible, use `unicode` if that's the only
-  possible type, and `Text` if it can be either `unicode` or `bytes`.
-* For arguments with default values, use `...` instead of the actual
-  default value.
-* Most type-checkers interpret optional parameters of the form `x : Foo = None`
-  as `x : Optional[Foo] = ...`. (So the former is a shortcut for the latter)
-  In typeshed, however, we prefer the explicit latter form.
-* When something is declared as taking only float, it also takes `int`. See
-  https://www.python.org/dev/peps/pep-0484/#the-numeric-tower. So write `float`
-  instead of `Union[int, float]`.
-* Avoid Union return types: https://github.com/python/mypy/issues/1693
-* Avoid invariant collection types (List, Dict) in argument positions, in favor
-  of covariant types like Mapping or Sequence.
-
+See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact
+syntax of the stub files and [CONTRIBUTING.md](CONTRIBUTING.md) for the
+coding style used in typeshed.
 
 ## Directory structure