Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Rewordings and corrections to Promise Basics #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iliakan merged 6 commits into javascript-tutorial:master from davegregg:master
Jun 12, 2018

Conversation

@davegregg
Copy link
Contributor

@davegregg davegregg commented Mar 27, 2018

  • Corrected a few things that seem to be leftovers from inaccurate translation.
  • Reworded several things to more natural-sounding English.
  • Added some more clarification in a few places.
  • Nearly replaced the "Handlers of .then/.catch are always asynchronous" section in an effort to make it more comprehensible for people who may be new to asynchronous operations.

Copy link
Member

@iliakan iliakan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The topic is subtle and important.

3. A *promise* is a special JavaScript object that links them together. That's a "list". The producing code creates it and gives to everyone, so that they can subscribe for the result.
1. A "producing code" that does something and takes time. For instance, the code loads a remote script. That's a "singer".
2. A "consuming code" that wants the result of the "producing code" once it's ready. Many functions in your "consuming code" may need that result. These are "fans".
3. A *promise* is a special JavaScript object that links the "producing code" and the "consuming code" together. In terms of our analogy: this is the "subscription list". The "producing code" takes the time it needs to produce the promised result, and the "promise" makes it available to all of the subscribed code when it's ready.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please reread the last sentence. Is it ok?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, maybe:

  1. A "consuming code" that wants the result of the "producing code" once it's ready. Many functions may need the result. These are "fans".

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, just getting back to this PR. Slightly reworded.

```

The function passed to `new Promise` is called *executor*. When the promise is created, it's called automatically. It contains the producing code, that should eventually finish with a result. In terms of the analogy above, the executor is a "singer".
The function passed to `new Promise` is called the *executor*. When the promise is created, this executor function is called (run) automatically. It contains the producing code, that should eventually produce a result. In terms of the analogy above: the executor is the "singer".
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe remove (run)?

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rephrased to (or, run) for clarification

1. The executor is called automatically and immediately (by `new Promise`).
2. The executor receives two arguments: `resolve` and `reject` -- these functions come from JavaScript engine. We don't need to create them. Insteadthe executor should call them when ready.
1. The executor is called automatically and immediately (by the `new Promise`).
2. The executor receives two arguments: `resolve` and `reject` — these functions are pre-defined. We don't need to create them. Instead, we should write the executor to call them when ready.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The word "pre-defined" is not as obvious as "come from JavaScript engine", how you think? I mean, the reader should understand that they are come from by Javascript itself.

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Compromise: "these functions are pre-defined by the JavaScript engine. So we don't need to create them."

```
The idea is that a job done by the executor may have only one result or an error. In programming, there exist other data structures that allow many "flowing" results, for instance streams and queues. They have their own advantages and disadvantages versus promises. They are not supported by JavaScript core and lack certain language features that promises provide, we don't cover them here to concentrate on promises.
The idea is that a job done by the executor may have only one result or an error. (If you are familiar with other languages, you might be aware of data structures which allow many "flowing" results, like streams and queues. They have their own advantages and disadvantages as compared with Promises. But as they are not supported by the JavaScript core, we won't be covering them.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Words about "familiarity with other languages" here are not terribly precise. Such structures exist in JS as well, and are quite well-known (just maybe not know to the reader yet). No need to mention other languages here.

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the parenthetical. Thanks!

```

For instance, it happens when we start to do a job and then see that everything has already been done. Technically that's fine: we have a resolved promise right now.
For instance, it might happen when we start to do a job but then see that everything has already been completed. That is fine: we have a resolved Promise immediately.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe "it might happen that we start to do a job..."?

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either works in this case. I rephrased this way: For instance, this might happen when we start to do a job...

```
If we're interested only in successful completions, then we can provide only one argument to `.then`:
If we're interested only in successful Promises, then we can provide only one function argument to `.then`:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the change completions -> Promises? Here we're talking about promise results.

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reverted to "completions".

```
If we're interested only in errors, then we can use `.then(null, function)` or an "alias" to it: `.catch(function)`
If we're interested only in errors, then we can use `.catch(errorHandlingFunction)`, which is just like doing `.then(null, errorHandlingFunction)`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...which is exactly the same, not "just like".

Copy link
Contributor Author

@davegregg davegregg May 14, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarified with your wording

````smart header="Handlers of `.then`/`.catch` are always asynchronous"
Even when the Promise is immediately resolved, code which occurs on lines below your `.then`/`.catch` can still run first. When the JavaScript engine sees your Promise, it will not only run the executor (the "producing code"), it will also go ahead and start executing code which occurs after your Promise and its `.then`/`.catch` calls.

So, when it is time for the function passed to `.then`/`.catch` to execute (nearly immediately in the case of an immediately-resolved Promise), the JavaScript engine puts it into an internal execution queue which will then already have items to be run.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new explanation is hard to understand for the person not familiar with the topic already.

So, when it is time for the function passed to `.then`/`.catch` to execute (nearly immediately in the case of an immediately-resolved Promise), the JavaScript engine puts it into an internal execution queue which will then already have items to be run.

In other words, when `.then(handler)`is going to trigger, it does something like `setTimeout(handler, 0)` instead.
The JavaScript engine is trying to do as many things at virtually the same time as possible. Everything is racing to get done. So, in the example code below, behind the scenes, you can imagine that the events might occur in this order:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"The JavaScript engine is trying to do as many things at virtually the same time as possible" - that's confusing. May seem like we're talking about multithreading, but we're not.

Copy link
Member

iliakan commented Jun 6, 2018

Is this PR dead?

Copy link
Contributor Author

Sorry, I've had to suddenly write a lot more curriculum for my code school, so I put this off, but I'm mostly done with the revision. Just have to finish the last big part, which I will do this weekend.

Copy link
Contributor Author

Alright, I have attempted to address all of your concerns. Please see the latest state of the PR.

Copy link
Member

iliakan commented Jun 11, 2018

Great stuff, @davegregg
By the way, are you interested to learn git?

I have a great screencast about it, much better than all I've seen (ok, I hope so, people can judge), it is being be translated to English, maybe you could review the text or even voice the English version?

@iliakan iliakan merged commit 482ec27 into javascript-tutorial:master Jun 12, 2018
Copy link
Contributor Author

Yeah, I'd be up for helping with that. I'm pretty comfortable with git, so it won't be an issue.

Copy link
Member

iliakan commented Jun 12, 2018

I added you as a collaborator.
As of now, the 1st issue text is ready: https://github.com/iliakan/git-screencast/blob/master/s1/e1-en.md

Please fix wherever you think is better. Also if you see any mistakes about git (hope there won't be any), let me know, so I can fix those in the English version.

P.S. Do you have Mac?

Copy link
Contributor Author

I do have a Mac. I might actually want to enlist the aid of a student of mine. It would be a good learning opportunity for them, and I will proofread the finished product when they are done. Would that work for you?

Copy link
Member

iliakan commented Jun 12, 2018

Hi,

Thank you very much for your wish to participate.

There are three parts here:

  1. Review the translation to ensure good English (needs only native English).
  2. Check the text to ensure correctness, just in case (needs good Git knowledge, but a student may be ok too, they can signal if an explanation is not clear and learn Git in the process)
  3. Voice the English version (may require a Mac, cause the screencast is written using Mac-only software, and normal/good English diction).

All that can be done by different people or by the same person.

Copy link
Contributor Author

Alright, let me loop in Jake (@jakerjohnson94) -- can you add him to the git screencast project? -- as I think he could do a good job with helping to ensure the correctness and naturalness of the English text. When that's done, I'll decide who will help record the English version. I'm assuming the English version will be just audio narration that will be overlayed on top of the video you've already taken?

Copy link
Member

iliakan commented Jun 13, 2018

Here's the repo: https://github.com/iliakan/git-screencast

I added Readme about the translation process.

Copy link
Contributor Author

I've started my student on the process of proofreading and we'll get back with you

azmo1213 pushed a commit to azmo1213/en.javascript.info that referenced this pull request Mar 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@iliakan iliakan iliakan requested changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /