Question: What impact does CoffeeScript 2 have on the decaffeinate project

First off, thanks so much for building this project! My team and I have recently just finished successfully decaffeinating all of our CoffeeScript code: ~200k lines of code, ~1400 files. So we appreciate this effort a lot.

I’m in the midst of writing a blog post detailing our process. One of the points I want to discuss is what the impact of CoffeeScript 2.x has. With the CS2 compiler outputting ES2016+/ES.next code, I was curious what your view is on how people should think about decaffeinate and the CS2 compiler.

Despite the output being somewhat comparable, the goals of the projects are of course completely different. One benefit of decaffeinate is the ability to preserve whitespace, formatting, etc. Another huge benefit is the tooling around with bulk-decaffeinate and integration with other tools like eslint, jscodeshift, etc.

Some differences I’ve taken note of so far:

• Project goals
  • Decaffeinate: one-time full conversion into ES.next code
  • CS2: Interoperability with ES.next code but still keeping CoffeeScript
• Maintaining whitespace, formatting
• Handling of bound subclasses
  • Erroring/providing potential polyfill vs run-time error (in the latest coffeescript@2.0.0-beta3)
• Behavior with polyfilling __guard__, __guardMethod__, __range__ vs inlining and declaring intermediary vars.
• Other instances where I would argue that decaffeinate outputs code much more akin to what a human may have output.
• Code architecture of the decaffeinate vs coffeescript projects
  • Multi-stage patchers vs compilation of AST
• No need for source maps since the purpose is doing a final conversion to ES code
• Probably many things I’m missing

Thoughts?

[alangpierce]

Hey @sudowork, thanks for sharing, really cool to hear that decaffeinate has been successfully used on such a big codebase!

Yeah, it’s certainly interesting to compare decaffeinate with CS2. CS2 is a language implementation and decaffeinate is a codebase conversion tool, so you can expect the objectives are different even if the tools are similar in what they do. As I understand things, CS2 wants to generate new-style JavaScript so that the languages can be closer aligned. If JS comes out with some fancy new feature, CS wants to just compile to that feature rather than needing to re-implementing it. And someone familiar with JavaScript who wants to try out CoffeeScript should find it familiar, but with a cleaner syntax, and not feel like there’s anything missing.

Your differences are pretty spot on. Some other things I might add:

• Theoretically, decaffeinate doesn’t need to care about correctness in obscure cases as much. For example, see How decaffeinate approaches correctness for a list of correctness issues that were intentionally not fixed in decaffeinate because they’re obscure and fixing them would make regular code look worse. decaffeinate also has a --loose option (really a family of options) that focuses on better code at the expense of 100% correctness, which wouldn’t make sense in CoffeeScript.
• CoffeeScript (including CS2) has less motivation to make the output code high-quality and idiomatic. That said, it often is quite high-quality compared to most code generators, since it helps people understand the language and helps people debug through the JS. But CS tends to not implement special cases like #1024.
• As of decaffeinate 3.0 (released a few days ago), decaffeinate now has a suggestions system that points out cleanup tasks that you might want to do, and includes a bunch of documentation on why the code looks a certain way. More generally, decaffeinate’s position is in being a tool to help you with a one-time conversion. For example, decaffeinate might in the future have an interactive mode where it asks you questions about your code or prompts you with multiple options and has you pick the best-looking one (although I don’t have any specific plans).
• decaffeinate is quite a bit slower than the CoffeeScript compiler. Performance is a low priority since it’s not meant to be run regularly.
• CS2 has some relatively minor breaking changes, whereas decaffeinate wants to run on all valid CS1 code. For example, this meant CS2 could come up with a pretty good compromise for the bound subclass problem.
• decaffeinate has a more well-defined scope; for example, decaffeinate would never add new CS language features.

Some other random thoughts:

• The __guard__ thing is annoying, and something I’m hoping to improve; see #336 and #1103. It’s mostly just the easiest thing I could do that works in all cases, rather than an intentional difference from CoffeeScript’s output. Arguably decaffeinate should focus on streamlining manual cleanup rather than generating nice-looking code. For example, even leaving a comment with the original ?. usages might be useful.
• I sometimes wonder if preserving formatting and whitespace in decaffeinate was a mistake. The patcher approach used by decaffeinate is relatively fragile and has let to a lot of complexity. It certainly has its advantages, but there are also some cases where decaffeinate generates poorly-formatted code that’s later cleaned up by eslint. And more and more people are using prettier these days, which intentionally discards all custom formatting.

[sudowork]

Thanks! Some of the codemods were definitely targeted towards patterns we had in our CoffeeScript codebase, but I hope they’re helpful 😃.