Assertions cleanup and new policy. All regression tests pass.

1 files changed, 37 insertions, 0 deletions

diff --git a/www/hacking.html.in b/www/hacking.html.in
index 37b13b5e..7af663aa 100644
--- a/www/hacking.html.in
+++ b/www/hacking.html.in
@@ -461,6 +461,43 @@ not all integer types have the same length across architectures. A long may
 be 4 bytes on a 32-bit machine and 8 bytes on a 64-bit. If you mean to skip
 4 bytes in a packet, then say so (or use sizeof(int32_t)).</p>
 
+<h2 id="malloc">Use assert(3) sparingly and carefully!</h2>
+
+<p>gpsd - I'm speaking of the daemon itself, not the clients and test
+tools - runs in a lot of contexts where it provides a life-critical
+service. We can't allow it to faint every time it gets a case of the
+vapors.  Instead, the right thing is to log a problem and soldier on.
+If the fault condition is in the logging machinery itself, the right
+thing is to just soldier on.</p>
+
+<p>Accordingly, there are very few asserts in the core code. Whenever
+possible we should avoid adding more.</p>
+
+<p>Here's the policy for the daemon and its service libraries.  This
+doesn't apply to client code and tools, which can be more relaxed
+because the cost of having them go tits-up is lower and recovery
+is easier.<p>
+
+<ol>
+<li><p>Use asserts sparingly.</p></li>
+
+<li><p>One valid use is to pass hints to splint and other analyzers. This
+sort of assert should be guarded with #ifdef S_SPLINT_S or #ifdef
+__COVERITY_ so we get the benefit of asserting the invariant without
+the risk of the assertion failing in production.</p></li>
+
+<li><p>Another use is to document should-never-happen invariants of the
+code.  Write this sort only if you are confident it will never fire
+in a production release; it's there to catch when changes in a
+*development* revision break an invariant.</p></li>
+
+<li><p>Outside the above two cases, do not assert when you can log an internal
+error and recover.</p></li>
+
+<li><p>Never use assert() to check resource exhaustion conditions or
+other dynamic errors.</p></li>
+</ol>
+
 <h2 id="nohash">Avoid git hashes</h2>
 
 <p>Style point: avoid using git hashes in change comments. They'll