Merge pull request adafruit#4185 from caternuson/doc_update

tannewt · web-flow · commit 766e79ad3dde · 2021-02-12T11:12:34.000-08:00
Design Guide Update - Exception and asserts
diff --git 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
 --------------------------------------------------------------------------------
 
