[llvm] 4778e40 - Clarify use of llvm_unreachable in the coding standard.

[Aaron Ballman via llvm-commits]

Author: Aaron Ballman
Date: 2020-03-26T08:08:23-04:00
New Revision: 4778e409de112dc4b70933f3e3f502d6c747ed5a

URL: https://github.com/llvm/llvm-project/commit/4778e409de112dc4b70933f3e3f502d6c747ed5a
DIFF: https://github.com/llvm/llvm-project/commit/4778e409de112dc4b70933f3e3f502d6c747ed5a.diff

LOG: Clarify use of llvm_unreachable in the coding standard.

There has been some ongoing confusion regarding when to use `llvm_unreachable`
which this patch attempts to address. Specifically, the confusion has been
around whether `llvm_unreachable` is intended to mark only unreachable code
paths that the compiler cannot determine itself or to mark a code path which is
unconditionally a bug to reach. Based on email and IRC discussions, it sounds
like "unconditional bug to reach" is the consensus.

Added: 
    

Modified: 
    llvm/docs/CodingStandards.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CodingStandards.rst b/llvm/docs/CodingStandards.rst
index 0e9bd8535b76..9c33f5b2c2ed 100644
--- a/llvm/docs/CodingStandards.rst
+++ b/llvm/docs/CodingStandards.rst
@@ -1153,6 +1153,13 @@ builds), ``llvm_unreachable`` becomes a hint to compilers to skip generating
 code for this branch. If the compiler does not support this, it will fall back
 to the "abort" implementation.
 
+Use ``llvm_unreachable`` to mark a specific point in code that should never be
+reached. This is especially desirable for addressing warnings about unreachable
+branches, etc., but can be used whenever reaching a particular code path is
+unconditionally a bug (not originating from user input; see below) of some kind.
+Use of ``assert`` should always include a testable predicate (as opposed to
+``assert(false)``).
+
 Neither assertions or ``llvm_unreachable`` will abort the program on a release
 build. If the error condition can be triggered by user input then the
 recoverable error mechanism described in :doc:`ProgrammersManual` should be