Docs: Revise docs to use ES6 position of splats

[markbrown4]

Now that CoffeeScript supports splats, rest and spread on either side of the variable name I think it makes sense to adopt ES6's position in the docs:

after... and ...before

It will be easier to adopt for those already familiar with the syntax in JS.

[GeoffreyBooth]

This was discussed in coffeescript6/discuss#85. We decided not to switch the docs because the style of CoffeeScript is to emulate English language syntax: that’s why it’s is and not ===, for example. The style of items... resembles English syntax, whereas ...items does not.

Just as we technically allow both == and is, we allow the dots on either side. But the docs are an expression of recommended style, and we’re trying to encourage an English-like style because we feel that it’s more readable; and more-readable code is one of CoffeeScript’s goals.

[markbrown4]

Hmm, I can see your explanation but I'm not convinced by your reasoning there - There isn't an equivelent to splat, rest and spread in English.

I think aligning with ES6 in the docs makes more sense than keeping a different implementation mainly for legacy reasons. @jashkenas here seems to suggest the same:

CoffeeScript 2.0 is a fine time to make the change to ...spread, if you're going to more closely align with ES6.

For those transitioning from JS to CoffeeScript changing the order of existing language features like this will be meaninglessly difficult.

[GeoffreyBooth]

People who prefer the JavaScript syntax are welcome to use it. Most people who use CoffeeScript nowadays are using it for the more readable syntax. That’s kind of the point.

The quote you chose is rather cherry-picked. Jeremy was referring to not allowing both syntaxes, not how we should present this feature in the docs. Obviously, by the end of the discussion we came to a different conclusion.

One place where I find myself using the ES-style dots is spreads of function calls:

export default
  computed: {
    ...mapState 'user', ['user']
    ...mapGetters 'user', ['profile']
  }

This is a case where I have to choose between implicit parentheses and trailing dots. The same could be expressed via mapState('user', ['user'])... but then I couldn’t leave out the parentheses.

If you want to add an example like this to the docs, hopefully something a bit shorter and more interesting, that would be welcome. It would show not only that the leading-dot syntax is an option, but when there are benefits to using it.

[markbrown4]

People who prefer the JavaScript syntax are welcome to use it. Most people who use CoffeeScript nowadays are using it for the more readable syntax. That’s kind of the point.

Which side of the variable ... sits on does not aid readability, all it does is add one more syntax to learn. I don't see a good reason here to swim upstream against es6 syntax.

Another way to think about this is that you could drastically simplify the Splats documentation by switching it up.

Splats, or Rest Parameters/Spread Syntax
They behave exactly the same as ES2015.

--

The quote you chose is rather cherry-picked.

Is it? I read it as Jeremy expressing that he'd adopt es6 syntax if he could, unfortunately you can't and keep things backwards compatible so you supported both.

--

FWIW I think you're doing a great job juggling many concerns of the upgrade, allowing for both syntaxes here was a good move. This one just seems like an unneccessary divergence from JavaScript syntax for no gain.

I'm thinking about JS dev's new to CoffeeScript - differences like this won't be positives, they'll be negatives.

[GeoffreyBooth]

We could simplify the docs about function calls by neglecting to mention that parentheses are optional. We don’t, because we feel that even though you can write CoffeeScript that’s closer in syntax to JavaScript, that doesn’t mean we want the docs to encourage such a style. The same goes for the dots. I personally feel that items... is more readable than ...items, because “items…” has a meaning in English that relates to items... in CoffeeScript; and ...items doesn’t. Clearly you’re more used to ...items, so you feel like it’s more readable because of familiarity with ES2015 rather than familiarity with English. We chose items... for the docs because everywhere else in the docs we prefer English familiarity to JavaScript familiarity. It’s a straightforward rule to follow, and provides a clear way to settle debates like this.

That said, the docs would be improved by including an example of leading dots that makes sense, that doesn’t detract from the English-first preference of the docs’ overall style. If you’d like to submit such an example, please feel free to do so.

[markbrown4]

I won't beat a dead horse any longer - you're the author.

In 4 years writing CS I did always err on the side of JavaScript syntax when they were equal length:

• == over is
• && over and
• I only omit parens from the first method call in a line, it's clearer than searching for commas
  • console.log example('yep'), 2
  • console.log example 'yep', 2
• I'd use ${} with backticks for interpolation if I could

CoffeeScript is Just JavaScript