Add note about approximating 'let'

[jez]

I found this discussion talking about let and const to be
helpful to understand the decisions why these keywords were not added to
CoffeeScript v2.

In particular, I think we can improve the documentation by linking to
these examples on the section about why they're unsupported. Basically,
it comes down to using do -> to approximate let and const.

I'm down to re-word anything here, and I also completely understand if
this is not something you want in the documentation.

[GeoffreyBooth]

The issue with this is that such a detailed discussion of workarounds for the lack of let makes it sound like there’s some deficiency in the language, like “you can’t get block-scoped variables, but you need that functionality, so here’s the closest approximation of it.” The part about using function arguments to shadow outer variables is especially hacky; that’s basically taking advantage of a loophole in the compiler.

In the discussions around the design of CoffeeScript 2, it was seriously considered (coffeescript6/discuss#62, coffeescript6/discuss#58) that we would make a breaking change to make all variables block scoped, instead of always function scoped the way they are now. Ultimately we decided not to go that way because it would be a significant breaking change, that would prevent a huge number of projects from being able to upgrade; but I think it’s still on the table for a potential CoffeeScript 3. Ultimately I wanted CoffeeScript 2 to be a bridge to get all projects into the modern JS era, and to not fragment the community the way Python is split between 2 and 3. And we may still make the same decision about scoping when 3 comes along, as it might still be too drastic of a breaking change. The other option discussed was an operator where you could define whether a variable should be function-scoped or block-scoped (coffeescript6/discuss#58), but that was rejected as then you lose the simplicity of not needing to think about variable declaration (all the more valued now that JavaScript has three ways to declare variables, between var and const and let, not to mention globals or function arguments etc.).

I think ultimately if you’re needing to use do -> to create little pockets of scope, and especially if you’re using do (outerVariable) -> to shadow variables, you probably have functions that are way too long. That’s not a polite answer, which is why we don’t say that in the docs, but ultimately CoffeeScript is very much an opinionated language (this is one of its opinions) and the opinions make assumptions about how code should be written; see also the get and set keywords. Coffeelint looks like it’s getting updated for CS2, and there’s https://github.com/pwlmaciejewski/coffeelint-variable-scope that’s supposed to help catch errors involving variables across scopes, so maybe that’s another way to go.