Interface vs. Implementation

What is more valuable: interface or implementation?

This is the most fundamental question in software development. Actually, it might be the most important question in most engineering endeavors.

I'm here to tell you that it is interface. Implementation is essential, of course, as nothing works without it. And good, fast, reliable implementations are immensely valuable. But while you can have interface without implementation (at least in software), you cannot have implementation without interface. Further, your project will always be judged first and foremost on its interface. This is as true of a simple command line utility as it is of a cutting edge video game. Even you, no matter how efficient and clever your implementation is, are more likely to judge your own software mostly by how simple/natural/intuitive/beautiful you consider the interface to be.

There are exceptions, yes. Tasks that are especially greedy for cycles or memory, big data, and the like. Preference in such things will tilt heavily toward performance. But not absolutely. Once competitors are all within "acceptable" performance standards--whatever those may be--the judgement refers immediately back to interface, with few exceptions.

And interface is harder. Interface is art. Implementation is science. Implementation starts (and usually ends) with a simple pass/fail test: does it work? If need be, you can move on to improving the robustness or performance of the implementation. But these are still simple tests. Does it break on unexpected input? Does this change make it faster or slower? Use more memory or less? Implementation skill is a straightforward matter of knowledge, education, and test code. There are reliable rules, clear choices. Good tests guarantee good implementations.

Interface is about intuition and aesthetics, balancing multiple dimensions of competing concerns. There are no guarantees and no rules, only probabilities and guidelines. There are no tests that can be written to pass judgement on an interface, only users can do that. Even when you are the only user, confident interface design can be a challenge; you are a moving, changing target. What is simple for you today becomes inflexible tomorrow. What is flexible becomes unmaintainable. What is concise becomes conflicting. What is explicit becomes burdensome. What is convenient becomes constricting. What is clear becomes confusing. Assumptions are dangerous, but overdesign can cost you both now and then.

Uncomfortable interfaces are THE impetus for coders to reinvent the wheel, over and over again. If there is a problem with the implementation or its performance, most will submit a patch for it. "Wait," you say, "they can't always get patches accepted. Might that not motivate them to reinvent?" You forget: the patch submission process (or lack thereof) is a feature of any project's interface. Interface is not just the API, it's the entire surface area of the project: name, website, license, documentation, developers, active community, and API. In every case, you'll find an interface is ultimately the problem that created the competitor, though implementation problems do, of course, contribute.

So, if interface is both more important and harder, the moral of the story is...

Prioritize it!

Make it a point to learn the strengths and weaknesses of different strategies for naming and structuring all aspects of a project. Never let implementation dictate, block, overwhelm, or otherwise hinder the interface. Expect problems to arise, both initially and as a result of your solutions to those problems. Never forget KISS, YAGNI, and the like. Never treat such acronymisms (ha!) as anything other than helpful guidelines. Don't write any tests (implementation!) until you have put in some time planning your interface or your interface will be better for testing than actual use. Strive to make your interfaces self-explanatory, intuitive, convenient, simple, flexible, robust, well-documented, consistent, extensible, logical, and familiar. Realize that many of those goals often become opposites when mired in the particulars of the real world. Balance is not always possible. Sacrifices must sometimes be made.

Good luck.

Dependency

The Java world has Maven and Ivy.  Tools meant to untangle dependency webs, to get you what you need, when you need it and put it where you want it.  I've seen a few attempts over the years to adapt Maven to handle javascript dependencies.  They were abandoned unfinished.  I haven't looked much in the last year.

Javascript development is immature.  Like Java 10 years ago, you generally need to manage the resources manually.  It's up to you to juggle version control, version numbers and untangle the web of dependency.  Once you have your libraries in their proper versions and understand what order you need them in, there are tools to help you execute what you decide/know.  RequireJS, yepnode.js, and Grunt interest me the most so far, but they all have different priorities and all get involved late in the dependency management problem. They help you execute deployment and development, but only after you have manually resolved all your dependencies.

Programmatic resolution is hard. To do it well requires organized public repositories, which require standardized naming, versioning, and dependency declaration. Not to mention bandwidth. The person and/or organization that takes it upon themselves to get this rolling in the javascript world has a lot of work cut out for them. But plenty of reward as well.

Ender does programmatic resolution, and it's package.json could probably be made to do more, but it only seems to run just one level deep, when a deep, tangled dependency web is the inevitable reality of any modular application development. It also neglects script loading, test running, support for app code, and stands as a competitor to other frameworks, not a complement.

Dependency management in the javascript world is harder than Java because javascript doesn't require compilation. Compilation funnels all Java devs through a common build step, making a natural insertion point for a dependency management tool. Javascript lacks that chokepoint. Testing, linting, minimizing, concatenating--all of these have some potential but are still inconsistently used or only used in production deployment, not development. And both deployment and development themselves often are embedded within build/deploy processes for whatever other platforms are being used to build the server side of the web app. Any javascript build process ultimately needs to work as a subprocess of those builds.

Javascript/HTML5 as a platform is still wild, untamed by the build tools and processes that smooth out other application development environments.  What i would really love to have in taming it is a dependency management tool that works with these features:

• Repository support - public would be great, easy tools or conventions for private ones are acceptable. CDNs only get us part-way there; wheel authors need to be able to post libraries.
• Standards for declaring dependency info - to optimize performance and untangle the web this should support/require:
• library name and version
• CDN URLs for the library
• global variables exposed by the library
• the libraries dependencies
• name
• version (range)
• when needed (execution, document-ready, window-load, optional, etc)
• license/copyright info
• Conditional script loading (for polyfills)
• Easy, declarative switching between development (test and lint, but no minimization or concatenation) and deployment (minimize and maybe concatenate)
• Plugins for easy integrating with other build tools (Ant/Maven/etc)

Support for non-browser javascript and things like passing modules into each other (to avoid global exposure) are bonuses.  I don't care about them currently, but other people will.

A large portion of the code seems to be out there.  Grunt build process, Ender dependency resolution, yepnope script loading, and you're already well on your way. If you build it, they will come. Well, i certainly will! I'd built it myself, but there are only so many hours in a day.


#javascript

Readable Code

Code needs to be readable.  Readable code is debuggable, re-inventable and extendable.  But not everyone seems to know what makes code readable.

Occasionally, programmers will use comments to explain their code.  Comments certainly can help make a section of code understandable, assuming the comments are intelligible and up to date with the code.  But they in no way make code itself readable.

    Comments should only ever be used to say things that the code itself cannot be made to say.

In other words, you can use comments to explain why a piece code is there, but not to explain what the code is doing.  Yes, there are legitimate exceptions to that explanation, but again, those all fall under the first statement.

Mindful of the value of self-documenting code, many programmers create code like this:

AddressMapper.prototype.setInitialLocation = function(initialLocation) {
    this.initialLocation = initialLocation;
};
AddressMapper.prototype.setContainerElement = function(containerElement) {
    this.containerElement = containerElement;
};
AddressMapper.prototype.renderMapWithEffect = function(effect) {
    //magic!
};
// and so on...

After all, this is self-documenting, understandable code.  No one can accuse them of being opaque or obscure, right?  Beware the evils of premature optimization, right?  YUI 2 was like this, so it's ok, right? No, it most certainly is not OK.  And YUI 2 made me want to cry.

While long, descriptive names are indeed much better than inscrutable acronyms and abbreviations, they do not always produce code that can be called readable.  The example above, is unreadable because it is repetitive, mind-numbing, finger-cramping blather. When code gets repetitive like this, eyes gloss over and even stupid bugs find it easy to hide. Granted, they are likely to do that no matter what, but code like this does not help. And it gets worse, when you create APIs like this, the app code using it ends up just as obnoxious:

var addressMapper = new AddressMapper();
addressMapper.setInitialLocation('Portland, OR');
addressMapper.setContainerElement($('#portlandMap')[0]);
addressMapper.renderMapWithEffect(AddressMapper.Effect.SLIDE_DOWN);

Verbosity is contagious. It spreads. It infects. It sucks the will to live.

When reinventing a wheel, you are not designing an independent feature.  You are creating an API.  Yes, the wheel must be able to roll and so the raw, unadorned functionality of the code is your priority.  But ugly wheels make for ugly vehicles, and no one wants those.

Readable wheel code must avoid needless repetition and be designed to encourage readable app code.  Now, imagine this fictional plugin as a jQuery plugin:

var map = $.fn.map = function(address, effect) {
    return this.each(function() {
       render(this, address, effectFunctions[effect]);
    });
};
function render(el, address, effectFn) {
    // magic!
};
var effectFunctions = {
    slideDown: function(){...},
    ...
};

Which leads to user code like this:

$('#portlandMap').map('Portland, OR', 'slideDown');

<div id="#portlandMap"></div>

The repetition has dropped to tolerable levels, but it's not exactly a picture of readability.  Let's take it a step further and follow all the Rules for Reinvention:

var map = $.fn.map = function() {
    return this.each(map.render);
};

map.render = function(element) {
    var $el = $(element),
        address = $el.attr('address'),
        effectFn = map.effects[$el.attr('effect')];
    // magic!
;
map.effects = {
    slideDown: function(){...},
    ...
};

$(document).ready(function() {
   $('map').map();
});

<map address="Portland, OR" effect="slideDown"/>

At this point, the plugin code is not only more readable, but the app code has become pretty much ideal--declarative, minimal and extremely readable.  In the end, this should always matter most.  Sometimes, for whatever reason, there will be an irreducible amount of complex, ugly code.  In such cases, you should always strive to absorb that mess into your library and keep your app code clean and neat.

                           A readable API takes priority over readable internal code.

In fact, the lower "level" a library runs at, the less readability matters (and the more test code does!)  Since wheel code is just one small step away from app code, your wheels should still be highly readable wherever possible.

HTML Validators Considered Harmful

There are these things out there called "HTML validators".  The last time i tried one was about 12 years ago.  There's a reason i haven't gone back.  It's not that i don't believe in standards; i do.  It's not that i'm sloppy or sneer at perfectionism; i don't!  I don't use HTML validation, because it doesn't work, won't work and shouldn't work.

HTML validation doesn't work because the browsers have never even come close to uniform standards coherence.  So the validators are testing markup against pure fiction, an idealistic but flawed dream of W3C hegemony.

HTML validation won't work because both HTML and browser versions are toast.  Over and done.  HTML has officially been declared what it always was: a fuzzy target.  Browsers have begun a version number war.  It is accepted dogma in web app development that you are doing it wrong when you check the user-agent string for any browser or version number.  Feature detection is the new game, and javascript is now used to emit so much markup into the document that HTML validators are a hopeless cause.

HTML validation shouldn't work, because it has always been worse than useless. It is constricting, a bane to innovation.  Why should app developers and wheel reinventors be restricted to a generic set of elements and attributes?  What good does it accomplish to place such a limit?  Like many other languages, HTML/XML is designed to be extended.  That creative ability should not be left only to the W3C and browser vendors.

In practical terms, browsers are spectacular at one thing, above all else: ignoring things.  They ignore extra whitespace, unrecognized elements, custom attributes, and even unclosed tags in many cases.  They do this so well out of necessity. Standard specifications have never been met.  They also need not only a high degree of backward compatibility, but forward compatibility as well.

Browsers are designed for new things.  Be creative!


The only valid kind of HTML validation is syntax validation.  All i ever want to know is if it is parse-able.  Really, that's it!

Give Controls Control - trigger.js

When you put a <button> or an <a> or an <input type="image"> into your markup, you intend them to do something, not just sit there and look pretty.  This inevitably means writing code like this:

$('a.blah').on('click', function() {
    console.log('blah');
});

STOP!  You actually meant to use a custom event, right?  Let's try that again:

$('a.blah').on('click', function() {
    $(this).trigger('blah');
});
$(document).on('blah', function() {
    console.log('blah');
});

Ah, much better. Sure, it's longer, but this way you are self-documenting and making your code easier to test, extend and maintain.

But what if it didn't really have to be longer? What if the button itself could be told to trigger the custom event. After all, that ".on('click'...)" business is just boilerplate and not particularly friendly to the world of keyboard accessibility. Well, this is what trigger.js does for you. Instead of setting up the custom event with some boilerplate javascript, we just extend HTML with a 'trigger' attribute:

<a trigger="blah">Blather</a>

$(document).on('blah', function(e) {
    console.log('blah');
});

Now there's no "blah blah blah" boilerplate; i get to focus on what i'm doing more than how i'm doing it.  It gives my controls control, rather than shoving their functions off into a separate file.  And this can be extended to accomplish even more.

But before we talk about the "more", here is trigger.js:


Wait, you say! Why isn't it just like this:
It could be that simple, true. If that's all you need, use that. But it's hard to resist adding a little flair when you are inventing the wheel. The first thing i wanted was sequenced events.  Why trigger just one when you can trigger more? After all, i like to "use custom events like crazy", and many "actions" in applications are actually combinations of sequential, dependent, but separate actions. Consider:

<button trigger="validate submit">Submit</button>

This way, my "validate" code doesn't have to be tied to "submit" code and so on.  And when "validate" fails, it can still call e.preventDefault() to keep "submit" from firing.

Once i had sequenced events in my markup, it was natural and easy to add them to jQuery's trigger function, especially for debugging things in the console.

$('#cancel').trigger('reset back');

That done, i remembered that i have long wanted to have my own custom event properties.  Instead of "moveUp" and "moveDown", i wanted to have "move" events where i could test for "up" or "down" properties, just like i test e.ctrlKey.  So, trigger.js now supports:

<button trigger="move:up next">Up</button>

$('#game').on('move', function(e) {
    var roll = dice.value();
    if (e.up) player.climb(roll);
    if (e.down) player.slide(roll);
    if (player.winner) {
        e.preventDefault();// all done
    }
}).on('next', function() {
    player = player.next();
});

Finally, i occasionally envied the ability to associate data with an event, like you can when calling trigger() on a jQuery collection. So i added that as well:

<button trigger="level[10]">Loud</button>
<button trigger="level[11]">Spinal Tap</button>

$(document).on('level', function(e, level) {
    speakers.goTo(level);
});

And finally, i wanted my apps to be more keyboard accessible. So, trigger.js also listens for 'enter' events on elements that don't naturally convert them to clicks (div, span, a[!href]) and does that for them.

By all means, if these extra features aren't useful to you, just use the simple, four-line version. But if you want to give your document's controls a bit more control, trigger.js is ready to help. :)

Code of Three Kinds

Client-side javascript can be generally be put into three categories:

• Frameworks  ("raw material")
• Plugins          ("wheel")
• App code      ("ford taurus")

The first two are what i often call "libraries".  They are reusable features and functions meant to be shared across projects.  The third is the code that makes your app what it is and is typically useless to others except perhaps as an example or template of how to use the frameworks and plugins.  Even then, it is often so busy and complex that it rarely works as a clear example.

Frameworks

These are the libraries we are required to use (See Use jQuery).  Probably single most distinguishing feature of these libraries is that your webapps can (and should!) pull them off of a CDN.  These have become part of the plumbing of the internet, and the more people who use a CDN for them, the better.  It speeds things up for everyone involved.

Another common reality about frameworks is that they usually offer far more features than any one app will use.  This is to be expected and accepted.  Customizing them to only download what you need defeats the point of common CDNs and all the caching available that way.  Don't worry about the extra code, it's not worth the worry.

Again, DON'T CUSTOMIZE and DON'T REINVENT, at least never a core feature.  These are not wheels, these have become the raw materials of a webapp.  Reinventing or rearranging them one molecule at a time is a waste of time, unless perhaps, you are doing it on behalf of a major tech company that plans to market and fund it all for you.

Plugins

These are what i am calling "wheels".  They are the shims, polyfills, widgets, extensions and other features that are used to build applications.  They are not specific to a particular application but are not likely to be needed or wanted by a majority of applications out there.  These cannot be found on CDNs but are rather all over GitHub and Google Code and hundreds of personal blogs and websites scattered around the internet.  For each polyfill or widget i might want, there are a dozen competing implementations, all of which do either too much or too little or both.  I usually think i could write them better myself and odds are 70/30 that i'm right.  This isn't just arrogance, the reality is simply that they wrote it for a particular app or audience that doesn't exactly line up with me and my app.  Personally, even when i'm wrong about this, i often learn some good things in the process of trying to write my own version or port one over to jQuery.

I will probably freely switch between calling these "plugins", "wheels" and just "js libs" to keep things confusing.

App Code

This is the code that uses the plugins and framework(s) together in a unique way to make your webapp (or just web page) what it is.  Unless your next app is merely a variation on your previous one, then you can expect that none of this will be reused.  And, in general, it is only worth talking about in the context of ways to reduce and simplify it via better plugins and frameworks.  Just as i would never pollute a framework with plugin customizations, i strive to keep my plugins free of app code.

Make sense?

Rules for Wheel Reinvention

Here's my rules for reinventing "wheels" for client webapp development:

• Never make the user call a 'setup' or 'init' method
• Declare configuration via DOM intuitive, "natural" elements and attributes
• Use jQuery
• Use custom events like crazy
• Expose your functions

Here's the explanations:

Never Make Users Call .init()

...because it's utterly redundant.  This isn't server-side java where you have no idea what namespaces and libraries have been pulled in by your Maven build and everything needs to be tightly managed.  This is the browser, baby!  Client coders frequently bend over backward to avoid including things they aren't using.  If your code finds itself loaded, consider that declaration of intent to be used!  Wait for window load or document ready and go for it!  Don't be shy about it, presence === permission to function!

Declarative, Intuitive DOM Configuration

This is really a logical extension of the first rule.  It does little good to avoid forcing init() calls if your code can't/won't know what to do without specific user instructions.  Remember, we're talking about "wheel" code here, not application code.  These things are meant to be generic and reusable widgets, components, and behaviors.  You shouldn't be writing a new fancy address mapping widget that makes the user call: AddressMapper.mapOnBlur($('input.address')).  Gag me!

Just extend HTML.  Seriously.  Browsers are wildly, amazingly robust markup processors. Running HTML through some fancy spec validation is generally a waste of time.  This is why HTML5 has officially become a moving target and those arcane doctype declarations are going the way of the dinosaur.  Just declare <!doctype html> and stop worrying about having 100% valid HTML.  The platform is developing too rapidly and inconsistently for anyone to be strict about following HTML specifications now.  Don't use invalid syntax, but don't be shy about creating your own elements, attributes and attribute values.

So, instead of exposing AddressMapper.mapOnBlur(), have addressmapper.js go looking for <input type="address" map-on="blur">.  Be creative, literally.  All browsers can handle this.  Both the code for your wheel and your user's app will be cleaner and clearer because of this.  Instead of three files to be coordinated (the wheel, the user's js and the DOM), there are just two.  The brain power and bloat saved here is well worth it.

Use jQuery

MooTools, YUI, Dojo and the like are all fine projects.  But jQuery is both everywhere and much more than good enough.  If you want to port your wheels to a different framework later, fine, but start with jQuery.  If your boss or customer has already committed to YUI, fine, but port to jQuery at your first opportunity.

But beyond all debates about which framework is best, you should not write your own code to do things that these frameworks all do: event binding, DOM traversal, DOM manipulation, etc.  Don't even write your own feature detection.  Use Modernizr.  The real point of this rule is that there are some wheels that you really, really, really should not reinvent.  The window for reinventing jQuery or Modernizr has long closed.  You cannot wisely develop a modern web app without using an established javascript framework. Deal with it.

Use Custom Events

This follows right with the custom attributes and elements business.  If your user's app needs to know when your code has done something, you should trigger a custom event, either on a related DOM element or else on the document.  You should NOT force them to do:

AddressMapper.doneMapping(function(map){ app.canUse(map); }); //BAD!

This violates the "Use jQuery" rule, since this is a textbook perfect case for custom events, a wheel that jQuery already adeptly "invented" for you.  Your AddressMapper should be doing $mapEl.trigger('doneMapping');  Then the user does:

$(document).on('doneMapping', function(e){ app.canUse(e.target); }); //GOOD!

This doesn't save the user keystrokes, but it saves them brain cycles.  They know jQuery's event system and don't have to learn one you reinvented.

On a lesser note, this also makes it easy for other wheels to interact with your wheel without creating a hard dependency.  And extensions like that are where the "like crazy" part comes in.  If it is useful for users or extenders to know when AddressMapper is 'doneMapping', it is probably handy for them to have a 'startMapping' event too.  Then they can configure something like a custom <loading> element to watch for both:

<loading on="startMapping" off="doneMapping>Creating Your Map...</loading>
             <!-- Heh. Now i want to make a loading.js that supports this... -->

The key thing here is this:  Events drive web app behavior.  If you are going to be adding behaviors to a web app, i strongly recommend that you use events to drive them too.

Expose Yourself

Make your functions accessible.  If you are a god among coders and your wheel is thoroughly bug-free, your "internal" functions may still be useful for extenders, coders trying to reinvent your wheel, or maybe even power users who want to add a little spice by wrapping a function.  And if you are human, being able to call internal functions sure helps other people find your bugs.  Heck, it may help *you* debug your code; who knows if anyone else will ever use it. ;)

Write your code to be readable, reusable, and recycle-able; leave the reduction to the minifiers and compressors.

For each wheel you write, you should have a single, descriptively-named object (or function) to which you attach all your functions.  This ideally matches the first portion of the file name.  Do NOT expose all of your functions directly in the global namespace.  Don't share all your variables under your primary object/function either; restrict yourself to the important ones.  You can expose this primary object/function as an attribute of the window, jQuery, or some other variable.  The only goal is to make it accessible to extenders and the console's command line.