[CS2] An explanation of why we don’t currently support certain features

[mrmowgli]

First draft, looking for comments, and of course figure out where this would go on the site.

[GeoffreyBooth]

Style notes: It’s spelled “ECMAScript” and “rationale”. Always “CoffeeScript”, never “CS”. Please use curly quotes (’). One space after a period.

Please don’t link to the discuss repo, as we will probably migrate those issues into the main repo sometime soon and @jashkenas has requested that future feature discussion happen over here. Just link to the main repo’s issues instead.

I think we should only mention features that we have decided not to support, and explain that decision. let/const, and block scoping/shadow variables in general, definitely merits a full section. get/set is only unsupported in that we aren’t supporting the shorthand syntax, though the syntax in the Crockford example (from his presentation slide) is really not much worse. That should probably be another short section, including the workaround. The other items on your list probably shouldn’t be here, as they might be supported someday. Regarding type annotations specifically, the consensus reached in the discuss repo was that a solution should be found (probably integrating a separate tool like Flow) and documented as part of the CoffeeScript docs.

There should be a section about support for future ES features. This section is where we would say that for consideration, the feature must be mature and at Stage 4, with no further potential syntax changes. Also, many new ES features are supported without us needing to do anything; when ECMA creates new methods on global objects, for example, they just work in CoffeeScript. The only thing holding back most features is developer interest in submitting a PR. At this point it should be rare for a new feature to fall into the “bad parts” category; aside from lack of interest and spec immaturity, the only other common reason we wouldn’t add support for a new syntax feature is if it conflicts too drastically with current CoffeeScript syntax or would create too large of a breaking change.

I like your text about what CoffeeScript is about and what it’s not. That deserves a section of its own; almost a “why CoffeeScript” section, explaining the language’s benefits such as ? and significant whitespace, and how such features help improve readability and reduce bugs.

[mrmowgli]

Great feedback, thank you! One of the things I was trying to work out is if this should all be addressed in the same place? For instance putting this and future support items all in the CoffeeScript 2 section?

[GeoffreyBooth]

I think sections should be concise and limited in scope—but we can have lots of sections. So the CoffeeScript 2 section shouldn’t say much more than it already does (in the 2 docs)—but we can add a section like “About” or “Philosophy” that includes your language for what CoffeeScript’s goals are. Not sure where in the outline it should go, though.

I think there should be a section called “Unsupported ECMAScript features” with subsections for “let/const“ and “get/set shorthand syntax”. Any workarounds for the lack of these features should be mentioned there in those sections. Right after that should be “Support for future ECMAScript features” explaining our criteria for those. (I don’t think we need to discuss support for future invented features.) I would put all this stuff maybe right before “Resources”.

[mrmowgli]

Are there any other items that are officially unsupported? I was racking my brain, but couldn't come up with anything. I also tried to dig through the old issues, but I didn't get far.

[GeoffreyBooth]

You can look through the discuss repo’s closed issues and “out of scope” section, but I think that just about covers it. Maybe mention the lack of == (as opposed to ===). I don’t think anyone cares about the lack of declarative functions (function foo as opposed to var foo = function).

I also won’t go into any more detail than strictly necessary in explaining why we choose not to support something. Link to comments, ideally from Jeremy and from the main repo, for reference.

See also https://arcturo.github.io/library/coffeescript/07_the_bad_parts.html

[jashkenas]

I don’t think anyone cares about the lack of declarative functions (function foo as opposed to var foo = function).

Some people care a great deal ;)

[mrmowgli]

@jashkenas What is the reasoning behind the lack of named functions? If you can point me to a good issue around this that explains it, that would help. I've personally never been bothered by this, so I've never really tried to find out before.

[mrmowgli]

@GeoffreyBooth Flow in the comments seems like it would work for type annotations, but not for general annotations. I really like the functional explanation used in the CS6 Discuss thread, is the plan to actually merge that repo in to the main CoffeeScript somehow?

[GeoffreyBooth]

Yes, @jashkenas wants all the issues in one place so we'll probably merge discuss into this at some point soon.

[GeoffreyBooth]

Do we have a style guide? Maybe this should just say that they should follow the style of the rest of the codebase.

[mrmowgli]

I can rip this line out. I was thinking that we probably should have a style guide in place.

[GeoffreyBooth]

This is vague, we could just leave it out.

[GeoffreyBooth]

This section should include a link to the wiki page where Jeremy has compiled a list of CoffeeScript’s derivatives.

[mrmowgli]

Ok

[GeoffreyBooth]

I think the documentation should avoid sounding judgmental. This section should probably be written more like:

get and set, as keywords preceding functions or class methods, are intentionally not implemented in CoffeeScript. This is to avoid grammatical ambiguity, since in CoffeeScript such a construct looks identical to a function call (e.g. get(function foo() {})) and because there is an alternate syntax that is slightly more verbose but just as effective:

(insert the best Object.defineProperty example here)

[GeoffreyBooth]

This section is way too long. I would try to reduce it to at most three paragraphs, and link to other sources to add more detail. Also try to write it in a dry tone like the rest of the documentation. Something like:

When CoffeeScript was designed, var was intentionally omitted. This was to spare developers the mental housekeeping of needing to worry about variable declaration (var foo) as opposed to variable assignment (foo = 1). The CoffeeScript compiler automatically takes care of declaration for you, by generating var statements at the top of every function scope. This makes it impossible to accidentally declare a global variable.

let and const add a useful ability to JavaScript in that you can use them to declare variables within a block scope, for example within an if statement body or a for loop body, whereas var always declares variables in the scope of an entire function. When CoffeeScript 2 was designed, there was much discussion of whether this functionality was useful enough to outweigh the simplicity offered by never needing to consider variable declaration in CoffeeScript. In the end, it was decided that the simplicity was valued more. Ultimately there is nothing provided by let or const that you cannot achieve with var and careful naming of variables, avoiding reusing variable names within the same function scope.

[GeoffreyBooth]

The documentation always refers to ES5 or ES2015 or ES2015+, never “ES6” or “ES7”.

[GeoffreyBooth]

This feels like marketing copy. I would maybe rewrite this section to focus on specifically what CoffeeScript offers that ES2015+ doesn’t. There are still many benefits that CoffeeScript has over ES2015+, most importantly (to me) significant whitespace/forced indentation, optional braces and parentheses, and the existential operator. When I introduce people to CoffeeScript and try to convince them of its value, I often use this example, with its JavaScript equivalent side-by-side:

if foo?
  foo()

This illustrates all three of my points:

• The existential operator does a proper check for truthiness, better than the if (foo) that most JavaScript developers would write. (Next I show them if foo?.bar?.baz?.)
• The significant whitespace/forced indentation and optional braces means that if someone edits this code down the line and puts a second line of code under the if, we don’t need to worry about remembering to add braces.
• Fewer braces and parentheses means less punctuation surrounding your code, which means there’s less to read and therefore less to be distracted by—and therefore bugs should be easier to spot.

[GeoffreyBooth]

Do you mind please giving me write access to this branch? There are lots of little things like this trailing whitespace, and misspellings, that are easier to just fix than point out in comments.

[GeoffreyBooth]

Hey @mrmowgli I did some large-scale editing, I hope you don’t mind. I think some of the extended discussion about let/const and other topics might be better in the wiki, which we could link to from the docs. The docs are meant to be read from top to bottom, so I don’t want any one section to get too in-depth. I took a lot of what you wrote and summarized or paraphrased.

I also threw some housekeeping into this PR:

• I added the one-liner example of how to transpile CoffeeScript through Babel via the command line. Closes [CS2] [Docs] Examples of module loading with external tools #4470.
• I updated the minimum Node version to 7.6.0, because that’s the version where async/await was first available without requiring the --harmony flag, and I took the async tests out from behind the “are we running in harmony mode?” check. This allowed some simplification of the CoffeeScript 2 section; now we can say that CoffeeScript 2 is fully supported in the Node 7.6+ runtime, excepting modules.

I hope this are now ready to merge. @mrmowgli, @lydell and @jashkenas, any notes? See the revised docs here, and in particular please read the CoffeeScript 2 and Unsupported ECMAScript Features sections.

[mrmowgli]

By all means, please merge in the documentation changes! I figured that anything I was adding was really just a starting point for a larger discussion.

[GeoffreyBooth]

Yes, and I feel bad cutting so much out! Feel free to add some pages to the wiki. I’m also looking forward to moving the https://github.com/coffeescript6/discuss repo’s issues over here, so that we can sprinkle more links into the docs with some of the great discussions we had over there. I think once 2.0.0 is out would be the time to move that repo, as its mission will have been completed.

Just going to give others a chance for notes, then certainly looking forward to merging this in 😄

[lydell]

This is great! 👍