Skip to content

Commit e059bc5

Browse files
ramsgoliMylesBorins
authored andcommittedJan 9, 2018
doc: change "Node.js style cb" to "error-first cb"
Change the awkward "Node.js style callback" phrasing to the more informative "error-first callback." PR-URL: #17638 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Jon Moss <me@jonathanmoss.me> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
1 parent a93ed5c commit e059bc5

File tree

2 files changed

+20
-18
lines changed

2 files changed

+20
-18
lines changed
 

‎doc/api/errors.md

+11-10
Original file line numberDiff line numberDiff line change
@@ -128,35 +128,36 @@ they are thrown *after* the calling code has already exited.
128128
Developers must refer to the documentation for each method to determine
129129
exactly how errors raised by those methods are propagated.
130130

131-
### Node.js style callbacks
131+
### Error-first callbacks
132132

133133
<!--type=misc-->
134134

135135
Most asynchronous methods exposed by the Node.js core API follow an idiomatic
136-
pattern referred to as a "Node.js style callback". With this pattern, a
137-
callback function is passed to the method as an argument. When the operation
138-
either completes or an error is raised, the callback function is called with
139-
the Error object (if any) passed as the first argument. If no error was raised,
140-
the first argument will be passed as `null`.
136+
pattern referred to as an _error-first callback_ (sometimes referred to as
137+
a _Node.js style callback_). With this pattern, a callback function is passed
138+
to the method as an argument. When the operation either completes or an error
139+
is raised, the callback function is called with
140+
the Error object (if any) passed as the first argument. If no error was
141+
raised, the first argument will be passed as `null`.
141142

142143
```js
143144
const fs = require('fs');
144145

145-
function nodeStyleCallback(err, data) {
146+
function errorFirstCallback(err, data) {
146147
if (err) {
147148
console.error('There was an error', err);
148149
return;
149150
}
150151
console.log(data);
151152
}
152153

153-
fs.readFile('/some/file/that/does-not-exist', nodeStyleCallback);
154-
fs.readFile('/some/file/that/does-exist', nodeStyleCallback);
154+
fs.readFile('/some/file/that/does-not-exist', errorFirstCallback);
155+
fs.readFile('/some/file/that/does-exist', errorFirstCallback);
155156
```
156157

157158
The JavaScript `try / catch` mechanism **cannot** be used to intercept errors
158159
generated by asynchronous APIs. A common mistake for beginners is to try to
159-
use `throw` inside a Node.js style callback:
160+
use `throw` inside an error-first callback:
160161

161162
```js
162163
// THIS WILL NOT WORK:

‎doc/api/util.md

+9-8
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,10 @@ added: v8.2.0
2121
* Returns: {Function} a callback style function
2222

2323
Takes an `async` function (or a function that returns a Promise) and returns a
24-
function following the Node.js error first callback style. In the callback, the
25-
first argument will be the rejection reason (or `null` if the Promise resolved),
26-
and the second argument will be the resolved value.
24+
function following the error-first callback style, i.e. taking
25+
a `(err, value) => ...` callback as the last argument. In the callback, the
26+
first argument will be the rejection reason (or `null` if the Promise
27+
resolved), and the second argument will be the resolved value.
2728

2829
For example:
2930

@@ -489,8 +490,8 @@ added: v8.0.0
489490
* `original` {Function}
490491
* Returns: {Function}
491492

492-
Takes a function following the common Node.js callback style, i.e. taking a
493-
`(err, value) => ...` callback as the last argument, and returns a version
493+
Takes a function following the common error-first callback style, i.e. taking
494+
a `(err, value) => ...` callback as the last argument, and returns a version
494495
that returns promises.
495496

496497
For example:
@@ -526,9 +527,9 @@ will return its value, see [Custom promisified functions][].
526527

527528
`promisify()` assumes that `original` is a function taking a callback as its
528529
final argument in all cases. If `original` is not a function, `promisify()`
529-
will throw an error. If `original` is a function but its last argument is not a
530-
Node.js style callback, it will still be passed a Node.js style callback
531-
as its last argument.
530+
will throw an error. If `original` is a function but its last argument is not
531+
an error-first callback, it will still be passed an error-first
532+
callback as its last argument.
532533

533534
### Custom promisified functions
534535

0 commit comments

Comments
 (0)
Please sign in to comment.