Mypy type correctness (#3199)

1 files changed, 26 insertions, 0 deletions

diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index 34fff7c4..39fa5244 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -31,6 +31,32 @@ if [ "$?" != "0" ]; then
 fi
 ```
 
+Type Annotations
+================
+
+We encourage the use of type annotations in Python code. 
+Type annotations make the code easier to read and understand, for example by making it clear what kinds of data functions accept as arguments and return.
+Editors and IDEs can also read this type information to power features like autocomplete.
+Type annotations also allow us to use the typechecker [Mypy](https://mypy.readthedocs.io/en/stable/#) to check for errors.
+
+A great reference for how to use annotations is the [Mypy cheat sheet](https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html).
+It covers most of the common uses and patterns.
+[Mypy's Common Issues page](https://mypy.readthedocs.io/en/stable/common_issues.html) is also useful for understanding the common pitfalls with type-checking you may encounter.
+Notably, Mypy does not perform type-checking on functions that don't have type annotations, but as we introduce new code with annotations we'll have better coverage as time goes on.
+
+You can run Mypy against your changes yourself simply by [installing Mypy](https://mypy.readthedocs.io/en/stable/getting_started.html#installing-and-running-mypy) running `mypy` in the project root.
+The project's mypy.ini file sets all of the relevant configuration, so no other arguments are needed.
+Mypy is also run as part of this project's builds on Github.
+Errors that Mypy picks up won't cause your build to fail, but will appear on Pull Requests so both you and reviewers can see the potential issues.
+
+Much of our code, especially older code, lacks type annotations.
+If you want to add type annotations to older code, or learn what types are used in a part of the codebase without type annotations, you my find [MonkeyType](https://monkeytype.readthedocs.io/en/stable/) useful.
+You can easily have MonkeyType collect type information from Ink/Stitch in a similar way to how you can use one of several profilers with Ink/Stitch.
+Simply copy `DEBUG_template.toml` to `DEBUG.toml`, and uncomment lines so that the `profiler_type = "monkeytype"`
+and `profile_enable = True` options are set.
+After running Ink/Stitch command, a window will pop up telling you how to run Monkeytype and use your newly-collected type information.
+Multiple command runs will all add to the type information database.
+
 Guidance and Comments
 =====================