From b7bd84f7d24822bfd4508af9b683572a34e88aed Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Wed, 20 Nov 2019 06:53:45 -0800 Subject: [PATCH] doc: simplify "is recommended" language in assert documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace "X is not recommended" with "Avoid X". Replace "It is recommended not to use X" with "Avoid X". PR-URL: https://github.com/nodejs/node/pull/30558 Reviewed-By: Colin Ihrig Reviewed-By: Michaël Zasso Reviewed-By: Gireesh Punathil Reviewed-By: Trivikram Kamat --- doc/api/assert.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index c590df9402bdc1..0997a2792d093e 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1234,10 +1234,11 @@ assert.throws( (err) => { assert(err instanceof Error); assert(/value/.test(err)); - // Returning anything from validation functions besides `true` is not - // recommended. Doing so results in the caught error being thrown again. - // That is usually not the desired outcome. Throw an error about the - // specific validation that failed instead (as done in this example). + // Avoid returning anything from validation functions besides `true`. + // Otherwise, it's not clear what part of the validation failed. Instead, + // throw an error about the specific validation that failed (as done in this + // example) and add as much helpful debugging information to that error as + // possible. return true; }, 'unexpected error' @@ -1288,8 +1289,8 @@ assert.throws(throwingFirst, /Second$/); // at throwingFirst (repl:2:9) ``` -Due to the confusing notation, it is recommended not to use a string as the -second argument. This might lead to difficult-to-spot errors. +Due to the confusing error-prone notation, avoid a string as the second +argument. [`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes [`ERR_INVALID_RETURN_VALUE`]: errors.html#errors_err_invalid_return_value