From 8b44641c4622fe3fdbe648ac5b518297e4f43c54 Mon Sep 17 00:00:00 2001 From: thk123 Date: Tue, 1 May 2018 16:53:17 +0100 Subject: [PATCH 1/2] Adding extra information about invariant messages to CODING_STANDARD.md --- CODING_STANDARD.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/CODING_STANDARD.md b/CODING_STANDARD.md index 98d8dc51386..c63610dd247 100644 --- a/CODING_STANDARD.md +++ b/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 From 43bfc739c34c9e4d2b53f02ca9762c277ee5fe49 Mon Sep 17 00:00:00 2001 From: thk123 Date: Wed, 30 May 2018 10:00:33 +0100 Subject: [PATCH 2/2] Update the invariant.h documentation to match CODING_STANDARD.md --- src/util/invariant.h | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/util/invariant.h b/src/util/invariant.h index 1b13dded769..d985bc2b0ad 100644 --- a/src/util/invariant.h +++ b/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.