We are all usually given an identifier at birth, called a name. They aren’t necessarily unique, but often close enough. I am “Andrew Henry Van Wagoner”. This name is supposed to represent all of me.

My name isn’t necessarily static, though. My family & friends have been calling my “Andy” for longer than I can remember, and most of my documents use “VanWagoner” (no space) to prevent software from tokenizing my last name incorrectly. My wife, like many people, legally changed her name when we got married. Though my name has an assigned meaning to it (manly), I doubt most people give it any thought beyond inferring my gender.

When we introduce ourselves, we rarely lead with our full names. “I’m Andy.” Sometimes we include our job function, department, or employer. “I’m Andy from Instructure.” This is where it starts to become more descriptive rather than identifying.

Once connected to the internet, we are given the opportunity to make up our own handle for ourselves. On the internet, nobody knows you are a dog. Am I “thewol” (meaning the warrior of light), or “imnd” (see what I did there?), or “boyz_ii_men_iv_ever”?

In 2005 I dropped my old “thewol@msn.com“ email address for the beta Gmail service as “thetalecrafter@gmail.com“. I figured I was going to make a career out of writing fiction, so it would be a fun way of introducing myself on subsequent online services. “I’m thetalecrafter.” I don’t remember feeling much attached to my prior “thewol”, so shedding that identity was painless.

It didn’t take long though for my anticipation of a writing fiction career to turn into an actual writing software career. And for more than a decade, I have presented myself with the handle “thetalecrafter”, giving people the impression, you know, that I craft tales.

Justifying this situation to myself wasn’t too hard though, as I did have a book I worked on periodically. And the label I had given myself pushed on me more than anything else to keep this book draft around. Over the years, work on my tales went from occasional (once every few weeks) to practically never (once every few years), and the handle continued to insist that this is who am.

As I used more and more services online, my handle “thetalecrafter” only became more entrenched. Twitter, GitHub, keybase, etc.

During this same time my once exciting email provider, the “do no evil” Google, went from being the shining example of making cool things that make the web better, to the stalker who follows you around, and strong arms the competition into adopting their “standards”.

As I switched from Googling to searching on Duck Duck Go, and I looked to leave behind “thetalecrafter” which beyond being inaccurate, gave me guilt about being the right me, I opted to go back to the name I inherited from ancestors. No matter what else changes in my life, my actual name was always going to be a solid identifier. I registered the domain vanwagoner.family and setup a matching email address.

Alas, several services I rely on do not think .family is a valid way to end an email address. So for two years now, I have drug along “thetalecrafter@gmail.com“ as a backup address. I don’t craft tales, and I don’t like Google.

Finally a straw broke the camel’s back, and I decided it was time to really ditch thetalecrafter. The handle, the email address, and the website (this one). On a whim I was looking at domain names, and found that vanwago.net was available. That would be a solid alias for vanwagoner.family, using a TLD that even AOL recognizes. Once I had the domain, I figured it didn’t make a terrible handle either.

Hi, I’m “vanwagonet”. I’m not on Facebook or Twitter these days, but I am on GitHub and LinkedIn, and every now and then I write things down on this site. I may spin some tales in the future, but even if I don’t, I’ll still be Andy VanWagoner.

My eyes were closed in an expression that probably looked like a wince.

“First time, kid?” asked the pilot in front of me.

I nodded without opening my eyes.

“You alright back there?”

I nodded again.

“I can’t see you back there, so you’re gonna need to give me a verbal.”

I opened my eyes. The tandem seats in this diminutive ship made me claustrophobic in addition to being anxious about the jump.

“I’m as ready as I’ll ever be,” I replied.

“Good,” laughed the pilot. “The fold should be right here in front of us. We are jumping on my mark. 3… 2… 1… mark.”

The stars blinked out in the distance. I expected some sensation of force, but there was none. I felt nothing.

Consciously I slowed my breath to calm my uneasy nerves, but the pounding in my chest only got louder.

I could still see the pilot in the dim light cast by the ship’s controls, but outside was complete darkness.

After a minute or two, the silence broke.

“Almost there,” said the pilot.

So our comms work in the fold.

“Just hang in there another few seconds,” she continued. “Done.”

As if flipping a switch, stars suddenly blinked back into view, but they were not the stars I saw only a moment ago.

The pilot tried awkwardly to twist around to look at me. “How was it?” she asked.

I hesitated to answer, so she offered a response for me. “Rather uneventful, huh?”

“Yeah,” I replied, “I was expecting a little more something.”

She laughed as if they all say that. “Welcome to fold jumping. You just traveled about a hundred meters in a direction we don’t have a word for yet, and landed two and a half million light years from where you started. Pretty cool, eh?”

No response came to mind. I just stared blankly at her.

After a moment, she rolled her eyes (I think; It’s hard to tell through her helmet) and she turned back to the main console.

“The station will take about an hour to reach from here through normal space, so I’ll get us going. You just collect your thoughts and let me know when you’re ready to talk.”

I nodded. She waited a minute.

“Verbal acknowledgment, please.”

“Okay,” I said.

“Thank you.”

No air. I desperately gulped at the void around my face, but I found nothing. Can’t think. Can’t breath. No air.

My captor unsealed the mask, and a hint of breath filled my starving lungs. Then again, it was sucked out and I was left gasping in vain.

The room tumbled about me, and the single light blinded me from everything else.

My insides lurched and the mask filled with bile. Again the mask was removed, and I collapsed on the ground. The bindings on my wrist tore into my flesh through the sudden fall. I barely noticed. I wheezed in the breath of life.

“We’re going to try this again,” rasped my reptilian captor. “Who else knows about this world?”

I shook my head with closed eyes.

The sudden force of a boot pressed every molecule of oxygen from my breast.

“Final question,” it calmly continued. “After I have suffocated you in your own vomit, into which star shall I send your remains?”

A weapons I couldn’t recognize rested against my head. In that moment I knew I could close my eyes forever. The searing pain in my chest and head would disappear. An accidental smile stole across my lips.

“You worthless filth, you.” it sneered, feathers frilling out around its head.

“I sent … a beacon,” I whispered, between shallow breaths.

“What did you say?” roared the creature, lifting me up to its face.

I tried to chuckle, but it turned into more of a cough. I took a solid breath and repeated, “I sent a beacon. It’s only a matter of time now.”

In disgust, my captor tossed me aside. In a moment I was alone, and the room was silent. Yet I waited. Rather, I rested, and tried to recouperate from near suffocation and being kicked by a being five times my mass.

The bite of the binding started to sting as my head cleared, so I got up and wandered to where my gear had been discarded. I took no time in locating my blade.

Once my arms were free, I made my way out of the makeshift shack, and trekked back to the starship. It was unharmed.
The data records synced to my ship’s main computer the instant I boarded, and a summary presented itself on the screen.

Stage 3 inhabitable planet
Single-cell colonization only
Massive deposits of fuel-ready organic mass
Massive deposits of a variety of metals

“Send report beacon?” the terminal prompted.

I accepted. I wouldn’t want to be a liar, now would I?

A small example to illustrate:

1
2
3
4
5

function getResult() {
  return new Promise(function(resolve, reject) {
    someAsyncFunction(resolve) // this function may throw an error asynchronously
  })
}

As you can see, reject never gets called. You must explicitly handle the error condition, or you won’t get so much as an error in the console. The error is thrown, but swallowed by the promise.

So why don’t I just handle the error? The point is not that errors cannot be handled. They certainly can be. The problem is that it is easier to do the wrong thing with promises. By default errors are caught and ignored.

Furthermore, async stack traces suck. This is a pain point for both promises and callbacks. Assuming an error occurs somewhere deep in asynchrony, the stack may only show you where the error was thrown, and have little or no context of where the function was called in the first place.

Both of these problems go away when using async function with await.

ES7 (or ES 2016 if you prefer) proposes a new keywords async and await. Under the hood, the new mechanism uses promises, but by default does the right thing.

The prior example becomes:

1
2
3

async function getResult() {
  return await someAsyncFunction()
}

This code assumes someAsyncFunction is also updated to the new syntax.

So what did we get?

1. If something goes wrong an error is thrown, and ends up in the console if not handled.
2. The stack trace is complete, so you can see what initiated the failed action.
3. A try/catch around your getResult() call works.

Want to know more about how async and await work? You can read Jake Archibald gush over their many virtues on his blog, or if you like, you can check out the surprisingly readable proposal.

Templates

First off, I admit I’m a reinvent-the-wheel kind of engineer. I readily find some minor fault in existing solutions and decide I have to write my own. EJS is really great, especially for someone coming from a PHP background, who doesn’t think logic-less templates are better than sliced bread. However, I really needed templates that can run asynchronously, doing file or network io for includes and other such magic.

So, I made Stencil. I was able to make templates that compile without mucking up the line numbers, so debugging is very straight-forward. No exception rethrowing necessary. The very-important async use case was satisfied without making all templates forced to use the async pattern.

1
2

sync_result = sync_tpl(data); // works if no async code in template
async_tpl(data, function(err, async_result) { }); // always works

Where the whole becomes more than the sum of parts: A small snippet makes it so I can directly require my templates, and get back the function instead of the string:

1
2
3
4
5
6
7
8

require.extensions['.html'] = function(module, filename) {
var fs = require('fs'), stencil = require('stencil-js'),
opts = { id:filename, src:fs.readFileSync(filename, 'utf8') };
module._compile(
'module.exports=' + stencil.compile(opts, true) + ';',
filename
);
};

Now the rest of my code that uses templates doesn’t have to care that I use Stencil. You just tpl = require('path/to/template.html'). This is possible because Node.js has an extensible require, and Stencil allows you to compile to a JavaScript string instead of just to a function. If I were to go back and change the templating system to EJS, Jade, or Mustache, I would only need to update this one little snippet.

Client CommonJS

I liked Node.js’s module system, and I didn’t want to have to replace it or use a separate system on the front end. Don’t get me started on mess of UMD. So, I created my own Modules library. You’ve heard about this before.

I got CommonJS modules to load (asynchronously) and run in the browser, so it was trivial to share code used on both ends. Again, line numbers weren’t munged in the server-side translation, so debugging works just like you always expect it to.

The library runs as a middleware for Express, enabling the reload functionality AMD lovers rave about, as well as standalone for concatenating and minifying bundles in the production build process. All with a client-side weight one-third that of AlmondJS, although that or RequireJS would also work on the front-end, since Modules still uses AMD as its transport format.

The real magic though, is that the Modules library has an option for translating certain types of files, giving us the same require functionality for our templates that we had on the server, and because the translation happens server side (or at build time), the client code can keep a Content Security Policy that disallows eval and unsafe inline code, as Stencil never has to be loaded in client code. (Lighter & more secure. Woohoo!)

1
2
3
4
5
6
7
8
9
10
11

app.use(require('modules').middleware({
translate:{
html:function tpl(name, file, src) {
var opts = { id:name, src:src };
return 'module.exports=' + stencil.compile(opts, true) + ';';
}
},
root: './components/', // file root path
path: '/module/', // url root path
// ... other options
}));

Backbone

One magic thing that I got for free, is that Backbone and Underscore are already CommonJS compatible, so passing them through the same middleware just worked. Async, and countless other Node.js modules also just work.

Adding it all together

While I chose to write my own templating and module components, many other libraries include the little hooks that make these synergies possible. Each component individually is really nothing spectacular, but when you put them all together you get a product that is cohesive from front to back, and really fun to work on.

Why do we prefix?

Prefixing is a kind of disclaimer for the feature. “Hey this is likely going to change, so don’t rely on it.” This seems in theory like a good way to go about it. If I am a browser maker, and I think of a cool new feature, like say, a gradient defined in css instead of an image, I really won’t know how good my design is until lots of people have used it and given feedback. Of course, if I am conscientious of the community and betterment of the web for everybody, I share my idea with other browser vendors and get their take on it too. Often we have competing ideas of how to implement it, so we want a way to distinguish between them. This competition is wonderful, and will lead us to a better solution. So, I make my background-image:-andy-linear-gradient(…), and my competitor makes their background:-steve-gradient(linear, color-stop(), …). Some people can try it out and it will work through the standards process and eventually everyone will have a background:linear-gradient(…) feature.

In theory it works out great, but what about in practice?

Here’s what actually happens, from a dev’s perspective.

My favorite browser, Shiny, implements a cool new feature: -shiny-gradient(). I play with it and think it’s really cool, but to be safe, I don’t actually use it in any production site. A year later, the other browser I support, Ice Monster has long since added their own -ice-gradient(). Two years later, pretty much every browser has their own prefixed version, even the Laggard browser.

Nice. It only took two years for the feature to be generally available, so I start to use it, even though my code looks like this:

1
2
3
4
5
6

background-image: -shiny-gradient(linear, left top, left bottom, from(hsl(0, 80%, 70%)), to(#BADA55));
background-image: -shiny-linear-gradient(top, hsl(0, 80%, 70%), #BADA55);
background-image:    -ice-linear-gradient(top, hsl(0, 80%, 70%), #BADA55);
background-image:    -lag-linear-gradient(top, hsl(0, 80%, 70%), #BADA55);
background-image:     -my-linear-gradient(top, hsl(0, 80%, 70%), #BADA55);
background-image:         linear-gradient(top bottom, hsl(0, 80%, 70%), #BADA55);

I don’t mind too much, because I use SASS or some other css pre-processor that actually takes care of all the prefixes and nuances. But this still bothers me in two important ways.

1. My stylesheets are getting much heavier than they used to be, which is a concern because I want people to be able to view my site quickly even on mobile devices. Most of the syntax is exactly the same, but I still have to write it over and over again for each vendor.
2. I have to opt in for each browser I want to get the feature. If a new browser becomes popular, it won’t get the gradients unless I go back and add yet another version.
   I complain, but I keep doing it anyway. Two years later (Now four years since it was first introduced), The standard is still a draft, and because I want to support not just the bleeding edge browser, even when the standard finalizes I must leave all of the vendor prefixes indefinitely.

The problem gets more real with mobile.

Management asks for a ShinyPhone version of our application. They don’t care about Robot, even though it uses -shiny prefixes. I am given enough time to make the ShinyPhone version, but no time to even test in Robot. Eventually though, I manage to get it working because I own a Robot phone.

A few months later, Catchup Phone 7, Ice Monster Mobile, and Concert Mini are showing up on more phones. They have their prefixed version of all the great Shiny features I used, but because I didn’t know about them, the mobile application looks awful, and would take me several weeks to fix for each new phone. Management is not willing to spend that kind of time, so even though they have all the features my site is broken for them. Who will our customers blame? It works on ShinyPhone, so it must be that Ice Monster Mobile just isn’t as good. Ice Monster and other browsers get blamed for my site not working well there.

The Solution?

It is clear that if other browsers want to make themselves look good, they have to do more than just implement the feature. If they just use -shiny prefixes, that would make my application work far better, and therefore make their browser look good. But that completely undermines what we’ve learned in the browser wars, and goes against the reason for prefixing in the first place!

We don’t really have a good solution yet.

However, I have an idea I think worth talking about. What if the feature hadn’t been prefixed at all? I would have been less nervous to put it into production, because CSS simply doesn’t apply rules that aren’t implemented, and though it will likely change syntax, I can add new versions, and the one that is implemented will work. My stylesheet ends up more like this:

1
2

background-image: gradient(linear, left top, left bottom, from(hsl(0, 80%, 70%)), to(#BADA55));
background-image: linear-gradient(top bottom, hsl(0, 80%, 70%), #BADA55);

My application just works for every browser that supports the feature with little thought or effort from my part, and if the spec doesn’t change, which it actually doesn’t change very often, I am already done more than four years before it is standardized.

Benefits of prefixing:

1. Sense of security for browser vendors, so they can change the implementation and make it better.
2. Web developers should be aware that the feature isn’t really ready yet.

3. Credit goes to the vendor who pioneered the feature.
   Benefits of NOT prefixing:

4. Less effort and maintenance for web developers trying to make their application (and browsers) look good. They don’t need to spend a lot of time researching which browsers support which features.

5. Lighter weight stylesheets for everyone, especially mobile browsers.
6. Browser vendors can focus on the features, not on evangelizing their prefix.
7. No -webkit- prefixes being supported by Mozilla. Dang, I said it after trying so hard not to.
   Honestly I do see the value in prefixing experimental and non-standardized features, but vendors have to break them often, and the standard needs to move faster if developers are realistically going to experiment with experimental features, and wait for the standard for production use.

Please feel free to disagree in the comments, check out the discussion going on in the w3c, or read up on other opinions. Better yet, get involved.

The problem is with patterns.

Patterns are great. They provide a toolbox that can lead developers on the road to “best practice”. But…

Patterns are a poor substitute for problem solving.

It doesn’t matter if you know how to make a Singleton, even if you know when a Singleton is useful, if the problem at hand is improving report speed. You need to know math, you need to know computation, and you need to find the unnecessary work being done. It’s possible we’ll use a Singleton, but it won’t be the solution to the problem.

In an interview, if I ask for code to find the most common words in a bunch of text files, “public class WordRanker {“ is unimportant. I’ve seen a few programmers struggle for the first few minutes to figure out if it should be a class, a function, or what language to use. But once, I was impressed by someone who quickly figured out what they wanted to do, and then said, “I’d google how to do that.”

The pattern is accidental complexity. Problem solving is essential complexity.

But WHY would you want to use CommonJS (formerly known as ServerJS) modules in a client environment?

Ideally you can share modules between client and server, but that requires you to use a server environment like node.js, which might make management really nervous. Even without sharing the CommonJS module system helps us avoid some annoyances in JavaScript development.

• Each module has it’s own scope. I don’t have to manually wrap each file in a function to get a new variable scope. (Of course, to achieve this, the boilerplate is going to have to wrap each module’s code in a function anyway.)
• Namespaces are only used in the require function, not everywhere in my code. Almost inevitably every web application I’ve worked in ends up using code like the following:

  1 2	var whatIWanted = new FormerCompanyName.Common.CoolLibrary.ConstructorName( More.namespace.chains.than.you.can.follow ); // the rest of this file continues to use these ridiculously long namespaces

Although I’m sure many will disagree with me, I much prefer the CommonJS way:

1
2
3
4

var CoolModule = require('common/cool-library'),
    thingINeed = require('more/namespace/chains/than/you/can/follow'),
    whatIWanted = new CoolModule.ConstructorName(thingINeed);
// the rest of the file is void of long namespaces

And much more importantly, when I define a new module (or class as some insist on calling them):

1
2
3
4
5

FormerCompanyName.Common.CoolLibrary.ConstructorName = function() {/* ... */};
// versus
exports.ConstructorName = function() {/* ... */};
// or even
module.exports = function() {/* ... */} // this case isn't in the spec, but I really like it, so I made sure my library can handle it.

• Because you can also use relative module identifiers (“./sibling-module”, “../uncle-module”), when the company changes it’s name, it can be as simple as renaming a folder to update all the top-level module ids.
• Additionally, modules can be included in the page in any order, and are only executed when first required, instead of all modules executing immediately upon inclusion, requiring the script order to be specific and fragile. If I add a new module using CommonJS, I can just append it to the end of the list, otherwise I have to make sure it is earlier in the page than whatever uses it, and after whatever it uses.
  Okay, but how much work is it going to be?

Let’s walk through first what I wanted my server-side code to look like, then what it has to do to make it work on the other side.

As most of my server-side experience thus far has been in php, that’s the first language I’ve used in my implementation.

1
2
3
4
5
6
7
8
9
10
11
12

<!DOCTYPE html>
<html>
<head>
    <title>My Awesome Application</title>
    <link rel="stylesheet" href="awesome-styles.css" />
</head>
<body>
    <!-- blah blah blah -->
    <?= Modules::script() /* include all necessary script tags */ ?>
    <script>require('awesome').go()</script>
</body>
</html>

The Modules class will look for all js files in the folder you put it in, and any subfolders, and will id them by their path.

Yes, I am including every module, not actually checking dependencies. I refer you back to my previous post and say this is the simplest way, and if the caching headers are working, the experience won’t suffer. You are welcome to use one of the fantastic libraries that loads modules on-demand, if you disagree.

Hopefully that is all the server-side API you need to worry about, but there is more if you need it.

So what is that library doing to my poor scripts to make the CommonJS module environment?

I will explain in detail what goes into it in another post, but if you are daring, you can check out the source on github.

As many who are immersed in front-end web development have noticed, HTML and SVG have different DOMs, different styles, and competing animation tools. They have been getting better, with HTML5’s inline SVG support, and browsers beginning to bring each markup’s features to the other, but the inconsistencies are still painful, and and they make implementation both for web and browser developers sub-optimal.

What I would love to see is something akin to the following document:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fancy HTML+SVG</title>
  <link rel="stylesheet" href="styles.css" />
  <defs>
    <path id="logo" desc="My Fancy SVG Logo" d="M59,0 l69,69 h-15 l-44,44 v15 l-69-69 h15 l45-45 5,5 -45,45 44,44 44-44 -49-49 z  M59,44 c0-8,10-8,10,0 v40 c0,8-10,8-10,0 z" />
    <filter id="soft_blur"><feGaussianBlur in="SourceGraphic" stdDeviation=".5"/></filter>
  </defs>
  <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48" href="#logo" />
</head>
<body>
  <header>
    <a id="home" href="."><use href="#logo" /></a>
    <h1>The TaleCrafter&#039;s Scribbles<h1>
    <h2>notes about science, fiction, and faith… but mostly web development</h2>
  </header>
  <article>My Article text and images and stuff go here</article>
  <footer>Boring Legal and maybe locale selection in here</footer>
  <script src="script.js" async defer></script>
</body>
</html>

styles.css

1
2
3
4
5
6
7

#logo { background:#111; } /* applies to everywhere <use>d, including favicon */
#home { width:64px; height:64px; float:left; }
#home path { transform:scale(.5); transition:background .5s ease; }
#home path:hover { background:#0d0dc5; }
h1 { filter:url(#soft_blur); transition:filter .5s linear; }
h1:hover { filter:none; }
/* ... lots more styles ... */

script.js

1

document.querySelector('#home path').addEventListener('click', /* open menu or something useful */);

Summary of things that would be cool:

• no need for foreignObject or anything like that, simply mix and match tags
• put all the useful attributes in the same namespace (make use is useful without xlink: namespace)
• css transitions & animations on svg styles (properties would also be nice)
• defs and use in html documents
• filters on html elements (Firefox is already working on this)
• unify styles like background and fill
• JavaScript DOM API identical
  In short SVG and HTML would be one and the same. You would style both with the same css.

Some nitpicks:

• I’m not sold on defining filters in markup, then using in style. It feels… odd. Why not define in style? (Oh no, that might be too much like IE’s filters! Gasp!)
• Animating is still a crapshoot. It feels like it should be in JavaScript, but declarative syntax is so much simpler, and easier to optimize for browsers. Some SMIL animations work in some browsers. CSS animations are still nacent but promising. (Even IE looks like it might implement it in ‘native HTML5’. Sorry, couldn’t help myself.) Still, JavaScript is the only reliable way right now.

Let me hear an Amen, or let me know what I’m missing. Leave a comment and let’s talk about it.

Don’t load any JavaScript until you know you need it.

I usually feel like this is the way to go, because a lot of my code is specific to a particular widget or workflow. Why make the page take longer to load initially for something the user won’t do every visit? Just put in minimal stubs to load the full functionality once the user begins down that workflow, or interacts with the widget.

Pros:

• Lighter initial page weight
• Encourages functionally modular code
• Memory performance boost (important if you have to support old browsers)
• Speed performance boost (if done right)

Cons:

• Adds additional complexity to code
• Laggy performance (if done wrong)
• Lots of HTTP requests

Combine and minify all JavaScript into one file loaded at the end of the html file.

You know beforehand what is going to be needed on each page, and YSlow warned you about too many HTTP requests. Bundle up all the scripts into one download which will be cached after the first page view.

Pros:

• Easy to implement (lots of code will do it for you)
• Initial page load (once cached) is really fast

Cons:

• Load a lot more than usually necessary
• Initial load can be much slower

So how do you know which pattern to follow? It depends! If your application is very complex, and large portions of the functionality are used infrequently, it makes a lot of sense to use an on-demand pattern. If your application is fairly simple, or if all of the code is likely to be used every time, then combining all of the scripts and including it from the start will be much easier.

I recently worked on a smaller application where I divided all the script into two files. The first was loaded initially, and provided enough functionality for the login dialog only. Upon successful login, the second script was loaded, which combined all of the remaining pieces of application.

The point I most want to make is this: Don’t just follow a pattern because it is a “best practice”. Take the time to figure out the best solution for your project.