Merge pull request #2142 from thk123/docs/invariant-message

Adding extra information about invariant messages

Author: danpoe

CODING_STANDARD.md

@@ -191,8 +191,14 @@ Formatting is enforced using clang-format. For more information about this, see
   - The type is explicitly repeated on the RHS (e.g. a constructor call)
   - Adding the type will increase confusion (e.g. iterators, function pointers)
 - Avoid `assert`. If the condition is an actual invariant, use INVARIANT,
-  PRECONDITION, POSTCONDITION, CHECK_RETURN, UNREACHABLE or DATA_INVARIANT. If
-  there are possible reasons why it might fail, throw an exception.
+  PRECONDITION, POSTCONDITION, CHECK_RETURN, UNREACHABLE or DATA_INVARIANT (also
+  see the documentation of the macros in `src/util/invariant.h`). If there are
+  possible reasons why it might fail, throw an exception.
+    - Use "should" style statements for messages in invariants (e.g. "array
+      should have a non-zero size") to make both the violation and the expected
+      behavior clear. (As opposed to "no zero size arrays" where it isn't clear
+      if the zero-size array is the problem, or the lack of it).
+    - The statements should start with a lower case letter.
 - All raw pointers (such as those returned by `symbol_tablet::lookup`) are
   assumed to be non-owning, and should not be `delete`d. Raw pointers that
   point to heap-allocated memory should be private data members of an object

src/util/invariant.h

@@ -23,10 +23,19 @@ Author: Martin Brain, martin.brain@diffblue.com
 ** evaluate to a boolean.
 **
 ** As well as the condition they have a text argument that should be
-** used to say why they are true.  The reason should be a string literals.
+** used to say why they are true.  The reason should be a string literal
+** starting with a lower case character.
 ** Longer diagnostics should be output to error(). For example:
 **
-** INVARIANT(x > 0, "x negative and zero case handled by other branches");
+** INVARIANT(
+**   x > 0,
+**   "x should have a positive value as others are handled by other branches");
+**
+** Use "should" style statements for messages in invariants (also see
+** CODING_STANDARD.md). An example would be "array should have a non-zero size")
+** to make both the violation and the expected behavior clear. (As opposed to
+** "no zero size arrays" where it isn't clear if the zero-size array is the
+** problem, or the lack of it).
 **
 ** To help classify different kinds of invariants, various short-hand
 ** macros are provided.