Lean HTML

By Evan — — Web

When I started working on the YUI 3 Cookbook, I spent more time than I should have waffling on how to format the code examples. The most obvious way to go would be to show the entire page, like this:

<!DOCTYPE html>
<html>
    <head>
        <title>Some Code Example</title>
    </head>
    <body>
        <div id="demo"></div>

        <script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js"></script>
        <script>
        YUI().use("node", function (Y) {
            Y.one("#demo").setContent("HELLOSKI");
        });
        </script>
    </body>
</html>

That’s a lot of HTML line noise for three lines of JavaScript. Possibly okay for examples that are many dozens of lines long. But most recipes in the Cookbook just illustrate a single principle, and so are deliberately quite short.

A better approach, I thought, would be to strip away all the markup and keep the focus on the JavaScript:

YUI().use("node", function (Y) {
    Y.one("#demo").setContent("HELLOSKI");
});

The JavaScript would be understood to be running in a boilerplate page with a handy demo <div>, a <script> element to load the YUI seed file, and maybe a yui3-skin-sam class on the body. I figured that designing the right boilerplate would cover over 90% of the examples — any example that needed slightly different markup could just show the full HTML.

But as I started working through the recipes, I discovered that no matter how I tweaked the boilerplate, I never got close to 90%. It was more like 60%. Some examples in the Loading chapter needed a different <script> URL. Other examples didn’t work very well with with a single demo <div> — they needed multiple <div>s, or a <ul>. Or they needed some unique CSS classes. I found myself distorting the JS examples to fit the HTML boilerplate. Not good.

So I dropped that plan and went back to showing the entire page, but with structural open and close tags stripped out.

<!DOCTYPE html>
<title>Some Code Example</title>

<div id="demo"></div>

<script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js"></script>
<script>
YUI().use("node", function (Y) {
    Y.one("#demo").setContent("HELLOSKI");
});
</script>

Valid HTML, minimal line noise, consistently shows the reader the complete context that the JavaScript is running in. Success!

Of course, omitting optional tags from the markup isn’t anything new and exciting. This is how HTML has worked forever. It was a particularly useful feature to have in your pocket back in 2003-2004, the era when misinformed XHTML advocates were running around that XHTML was kewler and in particular, “more efficient!” than HTML. Thanks to some very aggressive marketing from various Industry Thought Leaders, the webdev community had managed to conflate “XHTML” with “clean markup” and also “CSS-based layouts.” So you had to gently point out to people that not only was it possible to write clean HTML 4.01 Strict, but an HTML 4 page would always be shorter than the equivalent XHTML. It took time to undo the damage, but these bad memes have long since been banished to low-information “webmaster” forums, setting up the larger community to receive and accept HTML5. You’re welcome, Thought Leaders!

Anyway, after working with a leaner style for a while, what surprises me is that it’s the exception, not the norm. Omitting <html>, <head>, and <body>means:

  • Fewer bytes. Actually, this is the weakest argument in favor, because we’re not talking about a large number of bytes. You could save even more bytes by dropping close tags (which in some cases I’m okay with) and by unquoting your attributes (which makes me queasy). Eventually you start crossing over into the world of HTML minification, which seems a tough nut to crack.
  • Less line noise. The difference is most obvious for short code examples. But even in a real world page, cruft is cruft.
  • Simpler indent style. This is something that’s bugged me for nearly fifteen years, and possibly the biggest win. Do I indent the <head> and <body>? Do I indent the direct children of the <head> and <body>? Using a lean style removes all of these annoying decisions. The elements you actually care about start flush left. End of story.

My guess is that the reason this style looks weird has to do with pedagogy. Since the early 90s, HTML books and tutorials have all shown these structural elements explicitly. This is a good idea because it helps new students understand the structure of the document. Or if you didn’t learn by reading a book or tutorial, you probably copied-and-pasted your code from someone who copied-and-pasted their code from someone who did.

However, professionals don’t need this crutch anymore. Better to just put the head stuff at the top, the body stuff below that, and separate the two with a newline. Boom, done. It will stop looking weird and start looking AWESOME in a day. Two days, tops.

One solid technical reason to have an explicit <body> is if you need that element stamped with an ID or class before JavaScript loads. Or you might be following an in-house coding convention or style guide, which of course trumps anything above.

The one thing I’m not concerned about is that people will read the code examples in the YUI 3 Cookbook and exclaim, “OMG that’s broken HTML!1!” The audience for the Cookbook is JavaScript developers, and in particular, JavaScript developers who are looking for a framework good for building large, sophisticated web apps. At that point, the reader really needs to know how HTML works. If they don’t, they probably bought the book too soon.

One thought on “Lean HTML”

Comments are closed.