Leaping into node.js and JavaScript, part1

A close friend with tons of tech experience had been urging me to learn JavaScript.  He uses it all the time and loves it.  Last week the local library had a Sams book, Teach Yourself node.js in 24 Hours.  So I checked it out.  How hard could it be?  :-)  I have over twenty years experience in Java, and more before that in C, C++, Pascal etc.  All your classic strongly typed, O-O / procedural languages.  But I have zero experience in node.js, or anything.js, and JavaScript.  Let the adventure begin.

I always had the bias that JavaScript was a "toy language" just for browsers.  At least the second half is wrong.  The node.js guys took Google's Chrome JavaScript runtime engine out of the browser, so you can run JavaScript, for example, from the command line.  Just like a JRE lets you run Java.  Cool.  There is an npm installer to search for and download additional libraries.  It's very quick to get a toy "Hello World" HTTP server up and running.  So far, so good.

A couple of problems.

Many of the examples are of the silly "Hello World" variety.  Data is collected all well and good, and then they use console.log(theData) to output to the console.  Now, very few real-world apps are going to do that.  More importantly, doing it this way glosses over some issues with all the callbacks that are the bane, or blessing, of node.js.  (For a good time, do a Google search on "node.js cancer")  Depends on your brain.  In a real application, you want to pass this data on to something else, such as an HTTP reply, an HTTP/XML/JSON parser, etc...  And this gets tricky.  Simply logging to the console obfuscates some of the key themes of node.js control flow.

Many generic intro Javascript blogs or books have crappy code too.  All the code is glommed into a single huge file, variables are named "$", and prints to the console happen.  This is not proper software engineering!  Javascript / node.js may be the hot new nailgun that lets you build sites quickly and easily, but you still need to put studs in the wall and use electrical boxes.

I found the following site pretty useful:  How to Learn Javascript Properly, along with Learn Node.js Completely and with Confidence.  He's opinionated but I agree with a lot of them.

He suggests that you get "the absolute best editor (IDE) for programming JavaScript", JetBrains' WebStorm.  I agree completely.  It's free for 30 days, thereafter very affordable.  Don't know about you, but my time and sanity is worth way over $49.  And for a "traditional" Java programmer moving over it's great to be able to have some syntax help and a nice graphical debugger.  JavaScript is one of those loosely typed everything is an Object languages.  So many times opening up a variable to see "what the heck type is this?" and "what fields can I access?" is simply the best way to blunder along.

I had separately discovered the Leanpub online ebook, The Node Beginner Book by Manuel Kiessling, which you can buy along with Hands-on Node.js in a $9.99 bundle.  Do so.  So far I found both useful.  They actually talk a bit about how to structure your source code for a realistic application.  Not dumping everything into one huge file with $s as variable names!

Anyway, since he also recommends these books, another tip of the hat to him.  Since I like what's he's saying so far, I took his advice and ordered a more advanced book, Professional Node.js: Building JavaScript Based Scalable Software.  I'll let you know what I think once it arrives.

Finally, stealing a phrase from Bruce Eckel, a word about "Thinking in node.js".  Code flow does not flow in the normal sense.  There are callbacks.  You don't have an option.  If you can't buy into or grok the callbacks, don't use node.js.  It's gonna take me a while...  For example, here was some of my first, ignoramus code.  (It's using a popular request library to do basic http requests)

var googleBody = 'not there';

Request.get('http://www.google.com', function (error, response, body) {
    googleBody = body;
});

doSomethingWith(googleBody);  // like parsing the HTML...

This doesn't work!  You have to remember that the callback executes at some indefinite time in the future, so the googleBody passed to doSomethingWith is very likely to be 'not there'.  I really should have known this, and, when I realized it a couple of hours later after some struggles, it was a real Homer Simpson "Doh" moment.  But I'm learning.  More to come.

I don't get git and github

The whole add / commit / push throws me.  When I first described the system to my wife, a former techwriter for computer networking companies, she said "geez, that sounds strange and clunky, is that something from UNIX?".  Well, it is.  But I think I can adjust...

Anyway, what has me really stymied is how to publish javadocs to GitHub in a sane matter.  GitHub allows you can create a branch, hardcoded to "gh-pages", to hold docs.  But the problem is how to move up to date documents (generated manually, via ant, etc.) from some local folder into the proper branch of the GitHub repository.

I'm not the only one.  Here is a 15 step process from a question on StackOverflow.  Wow!

Here's a very similar StackOverflow question with a complex answer.  May be the best.  Involves a symbolic link between the second branch and the internal folder which is something I was considering.  Note that the question was raised two years ago and the answer hasn't been "confirmed".  And both questioner and answerer have a ton of experience (StackOverflow points).  There aren't any "oh yeah baby, that's right" comments.  So it's not like a bunch of smart people agreed that this was a wonderful solution.

Here is yet another solution.  Ant is nice but not required.  However, it does involve checking out one branch (the javadoc .html files) over the code branch, wiping out the .java code files (even though one might call this "reverting", they are gone, right?) which seems, well, bizarre.  Frankly, the whole branching / wiping out thing strikes me as bizarre   And the generated javadocs then get removed when you return to the main branch and checkout the code.  So you can't look at them anymore.

I think the seconds answer, with two folders, one per branch, with a link is best.

Question in general for git experts: do you usually keep branches in separate folders / separate clones?  Or do you throw them all together into one directory and trust git in overwriting all of your previous work?  Maybe I'm just too old fashioned and paranoid?  :-)