Merge remote-tracking branch 'upstream/main' into manual-tests

1 files changed, 18 insertions, 0 deletions

diff --git a/docs/design_guide.rst b/docs/design_guide.rst
index 7a8c76b50..331757034 100644
--- a/docs/design_guide.rst
+++ b/docs/design_guide.rst
@@ -165,6 +165,24 @@ use what.
 Here is more info on properties from
 `Python <https://docs.python.org/3/library/functions.html#property>`_.
 
+Exceptions and asserts
+--------------------------------------------------------------------------------
+
+Raise an appropriate `Exception <https://docs.python.org/3/library/exceptions.html#bltin-exceptions>`_,
+along with a useful message, whenever a critical test or other condition fails.
+
+Example::
+
+    if not 0 <= pin <= 7:
+        raise ValueError("Pin number must be 0-7.")
+
+If memory is constrained and a more compact method is needed, use `assert`
+instead.
+
+Example::
+
+    assert 0 <= pin <= 7, "Pin number must be 0-7."
+
 Design for compatibility with CPython
 --------------------------------------------------------------------------------