search

cujojs / when

A solid, fast Promises/A+ and when() implementation, plus other async goodies.
Other
3.44k stars 396 forks source link

Update api.md #438

Closed gdoron closed 9 years ago

gdoron commented 9 years ago

Fixed the doc, task and not work. I changed from work to task and not the other way around because task is the right term.

unscriptable commented 9 years ago

"task" and "work" seem so interchangeable to me. You seem so adamant about it, @gdoron. :) Can you explain why?

gdoron commented 9 years ago

Maybe because I come from .NET background and Task is the class responsible for... tasks... :)

briancavalier commented 9 years ago

@gdoron I agree that "task" is a good word. I also think "work" is a good word.

However, the way you've presented your pull request comes a across as "task is better because that's what .NET calls it" or "task is right because I like it better". Neither of those is an objectively compelling reason to change, as they only represent your opinion. JavaScript has no such Task class to use as mental reference point. A Java dev might want to name it callable or runnable, a Ruby dev proc or block, a Haskell dev f, because those are the "right" term in those languages. In general, when.js users have not expressed any confusion over the word "work".

While I like the word "task", landing a pull request declaring that something is "right" because .NET does it, and you prefer it, can come across as somewhat unfriendly.

All of that said, I'm open to continuing this PR. If you'll also update the jsdoc and function signature and poll.js, I'll be happy to review.

gdoron commented 9 years ago

I think you missed it. There was mismatch of work and task documentation and variable name, that was the motivation of the pull request, the work to task change. I only said that I decided to change from work to task and not the other way around because Task sounds more natural for me.

From reading the docs page now, I see that task is the word the docs use in other sections too.

On Mon, Mar 23, 2015 at 3:11 PM Brian Cavalier notifications@github.com wrote:

@gdoron https://github.com/gdoron I agree that "task" is a good word. I also think "work" is a good word.

However, the way you've presented your pull request comes a across as "task is better because that's what .NET calls it" or "task is right because I like it better". Neither of those is an objectively compelling reason to change, as they only represent your opinion. JavaScript has no such Task class to use as mental reference point. A Java dev might want to name it callable or runnable, a Ruby dev proc or block, a Haskell dev f, because those are the "right" term in those languages. In general, when.js users have not expressed any confusion over the word "work".

While I like the word "task", landing a pull request declaring that something is "right" because .NET does it, and you prefer it, can come across as somewhat unfriendly.

All of that said, I'm open to continuing this PR. If you'll also update the jsdoc and function signature and poll.js https://github.com/cujojs/when/blob/master/poll.js#L48-L58, I'll be happy to review.

— Reply to this email directly or view it on GitHub https://github.com/cujojs/when/pull/438#issuecomment-84991574.

briancavalier commented 9 years ago

@gdoron It would have been helpful if you had simply included the information in your most recent comment in the original pull request description.

I certainly appreciate your helping to improve the docs. I'll merge this.