Human JS
Published on
The Ebook
I read a free ebook titled Human JS. It was a quick and good read. I highly recommend it. It made me reflect a lot on the code I have written and makes me want to steam forward with new ideas while keeping code clean and simple.
The book goes over common problems, such as choosing libraries & writing hard to read code, how to organize full client JavaScript applications, and conventions for writing maintainable applications.
Read it, it only takes a couple hours: Human JS
The rest of this post is some of my personal takeaways from the book.
Human Readable Code
The third chapter goes over how to write code that is easily digestable.
Compare this example from the book:
// Assume this is an array of strings from somewhere
var myArray = ["hello", "something", "awesome"];
if (~myArray.indexOf("hello")) {
// Under what circumstances does this get called?
}
With this:
// Same array:
var myArray = ["hello", "something", "awesome"];
if (_(myArray).contains("hello")) {
// Also pretty freakin' clear!
}
This is something I strive for when writing code, but in practice often throw out the window to meet deadlines. Often this is to my chagrin when I'm the only developer capable of fixing bugs that come back. I often use LoDash as a quick way to boil simple things down to digestible function calls. But using LoDash has also gotten me into trouble when I start chaining all its methods together and creating stuff that makes other developers scratch their head when they come across it. It is a little bit of a trade-off in that I can write something concise with LoDash, but many other developers don't know the functions and don't have the LoDash documentation always up in their browser to reference like I often do.
Refactor and Organize
Another chapter goes over refactoring. A common mantra is to "Refactor early, refactor often". I can't agree with this more. Recently I was working on a complicated tree control and it ended up being a 3000+ line mess of a file. I despise these huge files. I refactored it a couple times, but obviously not enough. There ended up being no clear separation of view, controller, model, and service. The view is the most separated of the 4, but the rest have ended up there in that file. It became a hot mess to maintain and near impossible to add new features. If I did it again, I would be more proactive about keeping service calls, models, and business logic separate.
Suggested Conventions for Backbone and Ampersand
Most of the rest of the book goes over good ways to use Backbone and Ampersand.js views and models. Which is all very useful if you are looking to learn one of the libraries. The two libraries are nearly identical in use, but Ampersand.js comes with more goodies and I feel has a better concern for maintainability.
Cool Things
Check out their index.html example:
<!doctype html>
<!– served with <3, &yet –>
<script>
window.times = { start: new Date() };
</script>
<link href="/&!.css" rel="stylesheet" />
<script src="/&!.js"></script>
The entire clientside application is launched from that!
The suggested folder layout is pretty good in my opinion too:
models (folder):
Contains definitions for all models and collections. As a sanity check, none of these files should have anything related to DOM elements or DOM manipulation.
pages (folder):
The pages folder is where we store the views that represent a page rendered at a specific URL. Generally these are still just "views" but since they play a special role to our app, it's useful to put these in their own folder.
views (folder):
The views folder contains all of our Backbone views (that are not pages), so things like the main application view and views for rendering specific types of models, etc.
helpers (folder):
Here is where we put any clientside modules that are application specific, but are useful in other modules. For example, we might use this to put a helper module for reporting metrics back to our server that we want to do from several places in the app.
forms: (folder):
A place to store any form views we might have. We often want to reuse a form for both creating and editing a type of data.
app.js (file):
This is the main entry point for our application. It creates an app global variable and instantiates the main models and views.
router.js (file):
This is our clientside (Backbone) router. It contains a list of URL routes at the top and corresponding handlers, whose job it is to instantiate the right views with the right data from the url and emit instantiated page views that can be rendered into the page container by our main view.
libraries (folder):
This contains all the libraries we're using that are not structured like CommonJS modules. So things like jQuery and jQuery plugins will go here.
templates.js (file):
This is the module that gets created from the templates folder (see next). It's a single file with a function for each clientside template. This file gets auto-generated so don't try to edit it directly. Putting it in here lets us also require and use our template functions easily within our views. Each template has a corresponding template function. Each function takes your context object and returns just a string of HTML.
templates (folder):
Here is where we keep all our Jade files that get used in the client application. Anytime you're wanting to create HTML within the app, use a Jade template and put it in here. You can structure this folder in whatever fashion makes sense for your application. The important thing to understand is that folders become part of the template.js module structure. For example, in this template you'll see that there's a pages folder within the templates folder with a file called home.jade. To use the function that got created from that, you'd access it as follows:
It categorically disses a few libraries that I agree with. Namely Angular, Ember, and Knockout. They just do too much magic. You end up writing a lot of code to try and do something a library wasn't intended to do instead of just writing something the JavaScript way cleanly the first time.
- Tools where you build the app by writing code in JavaScript files, not by trying to declare too much of your app logic in your HTML (no AngularJS, sorry). Having to write application logic inside of a template feels like a violation of separation of concerns. It has some short-term payoffs and can make simple things really easy. However, when you want more control it can be difficult to do within the constraints of the framework.
- Model state is completely decoupled from view state (no Knockout.js). Again, this is to separate concerns.
- As little magic as possible (no Ember). Similar to Item 1 this is primarily to avoid requiring too much framework-specific knowledge.