From: Nick Mathewson <nickm@torproject.org>
Date: Thu, 7 Sep 2017 13:37:39 +0000 (-0400)
Subject: Talk about assertions in CodingStandards.md
X-Git-Tag: tor-0.3.2.1-alpha~95
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8421756da3fc3cc116d17fe96b50384c0d79af8b;p=thirdparty%2Ftor.git

Talk about assertions in CodingStandards.md
---

diff --git a/doc/HACKING/CodingStandards.md b/doc/HACKING/CodingStandards.md
index 55c23a7df5..a8fca4a770 100644
--- a/doc/HACKING/CodingStandards.md
+++ b/doc/HACKING/CodingStandards.md
@@ -249,7 +249,25 @@ end-users that they aren't expected to understand the message (perhaps
 with a string like "internal error"). Option (A) is to be preferred to
 option (B).
 
+Assertions In Tor
+-----------------
 
+Assertions should be used for bug-detection only.  Don't use assertions to
+detect bad user inputs, network errors, resource exhaustion, or similar
+issues.
+
+Tor is always built with assertions enabled, so try to only use
+`tor_assert()` for cases where you are absolutely sure that crashing is the
+least bad option.  Many bugs have been caused by use of `tor_assert()` when
+another kind of check would have been safer.
+
+If you're writing an assertion to test for a bug that you _can_ recover from,
+use `tor_assert_nonfatal()` in place of `tor_assert()`.  If you'd like to
+write a conditional that incorporates a nonfatal assertion, use the `BUG()`
+macro, as in:
+
+	if (BUG(ptr == NULL))
+		return -1;
 
 Doxygen comment conventions
 ---------------------------