kartograph/kartograph.js — Issue #12: Rewrite it in JavaScript
Author: shawnbot
Created: 2012-03-09 20:11:38+00:00
State: open

I know, I know: It's a pain in the ass. But please hear me out.

I wanted to make a tweak to `kartograph.choropleth()` last night, and I didn't have the CoffeScript compiler installed. So I went to edit the JavaScript directly, but it's littered with all of these cryptically named `_refN` variables, so it took me way longer to figure out what I needed to change than it should've. Eventually I got it working, and decided that [the change](https://github.com/shawnbot/kartograph.js/commit/e0f0a26ee763a9f7078f3ba3ca884574c070c2ff), though simple, was a good enough excuse to fork the project, apply the patch and submit a pull request.

So I installed CoffeeScript and edited the relevant bits. First I ran into [this issue](https://github.com/kartograph/kartograph.js/issues/11), but fixed that by just touching a blank `src/core.coffee`. Then `build.sh` completed successfully, so I did a diff to see what had changed in the output. And that's where things got really shitty: a one-line change in the CoffeeScript source resulted in a 911-line diff. Merging your latest helped, and now I can build without any changes, but it's really time-consuming to tell what changed in the generated source (mostly because of all the cryptically named variables, which appear to get new names any time you add a variable somewhere else in the code).

CoffeeScript introduces at least four totally unnecessary hurdles to contribution:

1. It's generally difficult to debug (or even read, in some cases) generated code, so people are more likely to just give up right away.
1. Contributing to the code requires people who don't know CoffeeScript to learn a new language and install a new piece of software on their systems, whereas if it were in JavaScript all it would require is a text editor.
1. Testing changes requires modifying CoffeeScript and building the JavaScript before you can test again, *or* modifying the JavaScript then having to transcribe your changes back to CoffeeScript, build and test again. That extra build step and the translation between two languages adds time and cognitive load to the entire process.
1. Diffs against the generated code are essentially useless because the entire file can be rewritten by single-line changes, which makes it hard to tell what really changed unless you understand CoffeeScript *and*, more importantly, *how it transcribes to JavaScript*.

I see all of these hurdles as potentially insurmountable barriers to entry for exactly the kinds of people you might wish to contribute: people with broad and deep knowledge of both the *actual* language in which Kartograph is executed, or of the technologies it depends on—all of which are written in native JavaScript, not CoffeeScript.

I'm more than happy to aid in porting the whole thing over to JavaScript if it's something you're interested in.