doc: add warning to assert.doesNotThrow()

Using `assert.doesNotThrow()` has no benefit over adding a comment next to some code that should not throw. Therefore it is from now on discouraged to use it. PR-URL: #18699 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Tiancheng "Timothy" Gu <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]>
nodejs · Mar 20, 2018 · 8e88a18 · 8e88a18
1 parent 411f3e0
commit 8e88a18
Showing 1 changed file with 5 additions and 0 deletions.
diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -330,6 +330,11 @@ changes:
 Asserts that the function `block` does not throw an error. See
 [`assert.throws()`][] for more details.
 
+Please note: Using `assert.doesNotThrow()` is actually not useful because there
+is no benefit by catching an error and then rethrowing it. Instead, consider
+adding a comment next to the specific code path that should not throw and keep
+error messages as expressive as possible.
+
 When `assert.doesNotThrow()` is called, it will immediately call the `block`
 function.