Chapter Eight: Best Practices for Modern Markup

At the heart of any site, at the heart of the web, is markup. It’s what browsers see, it’s what search engines see, and it’s what we as developers look at day in and day out. Writing clean, meaningful markup has many benefits:

• It makes our code much easier to maintain—for us and for other developers months or years after we’ve gone.

• It can help search engines index and rank our sites.

• It can help users find content on our pages more easily.

• It helps make more web content more accessible to people with disabilities.

In this chapter, we’ll look at some of the techniques, practices, and technologies that can help us produce cleaner, more maintainable markup that is easy for browsers, search engines, JavaScript, and other developers to interact with. First, though, let’s consider these benefits in greater detail.

Code Readability

All code, whether it’s written in a programming language such as C++ or JavaScript or in a markup language like HTML, has two audiences. The most obvious audience is software: compilers, interpreters, browsers, search engines, and so on. But code has another important but often overlooked audience: developers. We’re likely to revisit our own code many times during its development and maintenance, and on most web projects, many other developers will also need to view and maintain our code.

Code that is easy to read is usually easier to maintain, to debug, and—by virtue of its intelligibility—easier to get right in the first place. The past four decades of software engineering have produced many practices that we can apply to our markup (and our CSS and JavaScript), including the use of sensible names and naming conventions, the use of formatting to aid legibility, and the use of commenting to explain coding decisions and aid readability.

Naming

Once upon a time, computer memory was rare and precious. As a consequence, brief variable names and compact code were necessary. These days are gone, but many of us code as if they weren’t. Yes, more compact code can improve website performance, but these improvements can be attained without compromising readability by compressing code served to browsers while maintaining legible, “verbose” versions of files for development. (You’ll find links to performance improvement resources at the end of this book.)

We’ll consider semantic naming practices in a moment, but for now, let’s just note that names should not be so short that they become cryptic. Make names meaningful, and where conventions exist—whether they’re public, like Electronic Commerce Markup Language (ECML) or microformats, or for internal use only—reuse those conventions.

Formatting, Commenting, and Consistency

Sensible code formatting enhances readability, and unlike many programming languages in which whitespace is significant, HTML and CSS allow us to format markup (with tabs, carriage returns, and spaces) as we please, with no impact on the way browsers parse the code.

The simplest and most important HTML formatting technique is to indent child elements so that the document’s hierarchy is clear at a glance. Compare the readability of this block of markup:

to the readability of this one, which is identical except that it’s formatted using indents to indicate element nesting:

Commenting can further aid the readability of such code. Although it’s relatively easy to match the opening and closing tags of the two div elements in this example, in more complex real-world situations in which divs may be nested several layers deep, matching opening and closing tags can be quite difficult. The resultant mistakes can produce invalid pages with unpredictable and difficult-to-debug rendering problems. A simple way to overcome this problem is to add a comment to each closing tag of deeply nested elements, like this:

Consistency of formatting, commenting, and other markup practices—always using the same class and id naming format, always quoting attribute values, and so on—is another quality of readable code. And whether we do it for that reason or not, consistent coding practices also make it easier for us tell when there’s something not quite right about our markup.

Readable code is easier to maintain and is less likely to be invalid or otherwise incorrect. The preceding techniques, simple as they are, can save hours of development time and make even small web projects run more smoothly.

Plain Old Semantic HTML

As we’ve noted before, the semantic toolset of HTML is limited. We have headings, paragraphs, lists, and a few other basic building blocks for any document. Fortunately, HTML does provide a mechanism for adding richer semantics to our documents via the class and id attributes. But before we dive into some of the current best practices in using these techniques to enrich our markup, note that the semantics we add to our documents in this way are only conventions—they aren’t part of any official standards. Although web applications, browsers, and even search engines are beginning to take advantage of some of these conventional semantics (particularly microformats), the best reason to use them now is that they produce more readable and maintainable markup. Markup written this way also tends to work better with JavaScript—and to be more easily styled using CSS—than markup written without attention to conventional semantics.

“Plain old semantic HTML” (POSH) is a recently coined term for the practice of using the core aspects of HTML intelligently to create clean, meaningful, readable markup. To write POSH, you should:

• Use valid HTML or XHTML.

• Avoid any presentational markup, including tables used for layout.

• Use the most semantically suitable HTML elements and attributes for your document.

• Use meaningful class and id values where appropriate.

We’ve already considered the first two of these three guidelines in Chapter 3, so let’s focus on the third and fourth.

Using HTML Elements, class and id for More Meaningful Semantics

Beyond commonly used elements like paragraph and headings, HTML provides a number of other elements and attributes that help us produce more meaningful markup.

Quotations

HTML has two elements that are intended to be used for quotations: q for inline quotations, and blockquote for block quotations. Both may contain a cite attribute, whose value is a URL for the source of the quotation.

Definition Lists

In addition to ordered and unordered lists, HTML includes the definition list, which is designed for marking up definitions and their descriptions. You might use these elements to mark up, for example, a dictionary entry with a word being defined and one or more definitions. Here for example is how we might mark up a dictionary entry (definition courtesy of Wiktionary, www.wiktionary.org):

Note how here we have two definition descriptions for the single definition term. dt elements appear first in a definition list but may have any number of associated dd elements.

rel and rev

In HTML, the link and a elements can include rel and rev attributes, which describe the relationship of the link’s destination to the document containing the link. For example, we can link to a document and use a rel value of “license” in the link to indicate that the document we are linking to is the license (which might contain, for example, copyright conditions) for the document that contains the link. Here’s what that markup would look like:

Bonus point: the preceding example is both a microformat and a widely used convention.

The much less frequently used rev attribute is used to describe relationships that go the other way: it describes the relationship of the document containing the link to the link’s destination. (If you find this confusing, you are far from alone. At the time of this writing, the rev attribute is slated for removal from HTML5.)

abbr

The abbr element can be used to mark up an abbreviation or acronym. The title attribute of the element can then be used to mark up the long form of the abbreviation. For example, we might write:

class and id

The class and id attributes are perhaps the most commonly used “hooks” for extending the semantics of an HTML document. Any HTML element can take these attributes, and they are both central to microformats and a useful way of marking up a document so that it can be styled easily with CSS.

As we saw in Chapter 3, we need to follow some syntactical rules when using the id attribute. Values for this attribute must begin with a letter, and may contain only upper- and lowercase letters, numbers, underscores (_), hyphens (-), colons (:), and periods (.). They should also be meaningful and should focus on the semantic nature of the element, not its appearance. For example, if the left-hand column of a page is used for site-level navigation, it makes much more sense to mark it up as:

than as:

Why is this important? As we’ve said before in this book—and will say again—we should always separate presentation for the underlying content of our markup as much as possible. It’s far more likely that a site’s appearance, rather than its underlying content, will change. There will almost certainly be site-level navigation on your site for years to come, but it may not always be on the left side of the page. If we use sensible, non-presentational names, markup will continue to be meaningful for far longer than it would be if we encode presentational details into the HTML.

Less is More

Just how much should we annotate our elements with class and id values? Does it make sense to add a class or id attribute to most of the elements on a page? Some of them? And which ones? And when should we be using id instead of class?

We’ll start with the last question. id attributes identify unique elements on a page, so any given id value may only be used once on each page. Some components, like divs used for page headers and footers, will naturally occur only once per page, so it makes sense to use id attributes for these elements. When a page component may appear on a page more than once (even if it only appears once on some pages), then class is the appropriate attribute to use.

Which elements should we mark up using class and id? Developers often use class and id extensively to provide “hooks” for styling their pages with CSS. The groundbreaking and rightfully famous CSS Zen Garden (www.csszengarden.com) provides the following class- and id-enhanced markup as the basis for its CSS gallery:

A rule of thumb: When an element is a significant part of the document structure (a section like a blog post, an article, a block of navigation, and so on), class or id values should be used to “annotate” it and provide semantic information about its role and contents. The roles that the Web Accessibility Initiative’s Accessible Rich Internet Applications Suite (WAI-ARIA) specifies for its role attribute—turn to Chapter 6 if this doesn’t look familiar—provide good examples of the sort of semantics we might add. Additionally, HTML5 (discussed in Chapter 11) introduces new structural elements that provide great examples of the kinds of elements we should consider annotating with the class and id attributes. (Some examples from HTML5 include nav, header, footer, section, and search elements.)

As we’ll see later in this chapter, the microformats project also provides a number of models for marking up the sort of content that is commonly found on the web, such as contact details and calendars.

Electronic Commerce Markup Language (ECML)

Most browsers feature “auto filling” of form fields, which is a great timesaver when you’re filling in details such as your name and address. Different browsers have different ways of deciding how to auto-fill fields, but many now support the curiously little-known ECML, which provides a standardized set of form field names that can be used as the value of the name attribute of form elements.

ECML covers a very broad range of information commonly required for e-commerce transactions, including shipping information, billing information, credit card information, user and order ID numbers, and much more.

It’s easy to use ECML names as values in name attributes—we simply find the appropriate ECML value for a given field and mark it up:

Markup and SEO

You’ll find a great many search engine optimization experts (and web developers for that matter) who extol the virtues of a particular markup practice for improved search engine placement. The truth is far more complex. Search engine developers—especially Google—keep the exact nature of their ranking algorithms secret to minimize the impact of people trying to “game” their algorithms.

So how can we gain better search engine visibility through better markup? The first thing to note is that markup is one piece of the puzzle. The content of a site is a key determinant in a search engine’s assessment of that site. On the whole, search engines consider visible content just as important as—if not more important than—metadata such as meta element keywords.

A semantic, standards-based approach usually produces simpler, less obfuscated markup, making the content-to-code ratio much higher—something often considered to have search engine placement benefits.

Although there’s no conclusive proof that using semantic markup will produce specific search engine benefits, it certainly won’t hurt—and given the attention Google and Yahoo are paying to structured content like microformats, it would seem that search engines will increasingly value structured semantic content.

Microformats

The microformats project (www.microformats.org) is one of the biggest and most exciting areas of semantic innovation on today’s web. The project is a loose, collaborative effort to create patterns of markup and then use these patterns to create specific formats for commonly found types of information. By providing these formats and promoting their adoption, the project hopes to standardize—by convention, rather than through a standards organization such as the W3C—the markup of common information on the web. It also seeks to encourage interoperability between web content and applications such as address books, calendars, and mapping services, and to foster the development of services that can consume this structured semantic data.

The Benefits of Microformats

For developers, there are three significant benefits to using microformats. First, microformats provide sensible formats for marking up common types of information (such as addresses and other contact details, event details, and locations) that developers are likely to mark up on many if not most of their projects. Rather than developing your own markup patterns for these kinds of information, you can simply use the appropriate microformat. Microformats are designed to be very flexible—they frequently don’t require you to change your current markup at all, other than to add class attributes to existing elements.

The second main benefit of using microformats is that once you’ve implemented microformats, you can use various services and JavaScript libraries with very little effort. For example, you can use the X2V service (www.suda.co.uk/projects/X2V) to add a special link to any page that has event details or contact details marked up with the appropriate hCard and hCalendar microformats. This link will enable users to add these details to their own calendars or address books with one click, and if you’re already using microformats, it takes almost no development effort to add the service to your site. You might also use a library like Oomph (www.visitmix.com/lab/oomph) to add a toolbar to your pages that lets users perform various actions on microformatted content at your site—and again, you can do so with very little effort on your part.

One of the biggest long-term benefits of using microformats in your markup is that, as mentioned briefly in an earlier section of this chapter, Google now indexes some microformats, and Yahoo’s SearchMonkey and BOSS search engines index many different microformats.

Google indexes, among others, the following microformats, and uses them to display additional “Rich Snippets” of results [8.1]:

• hCard for contact details

• hReview for review details

• hProduct for product descriptions

8.1 Google displays some results, like reviews marked up with the hReview microformat, as a Rich Snippet.

Through two search APIs (SearchMonkey and BOSS) that developers can use to build their own targeted search applications, Yahoo indexes various microformats and makes these indexes accessible to third-party developers. Yahoo indexes, among others, the following microformats:

• hCard for contact details

• hReview for review details

• hCalendar for event details

• geo for locations

• adr for addresses

Microformats in Action

So, how do we actually use microformats? Each of the now two dozen or so draft or fully specified microformats is designed to provide a sensible, interoperable way to mark up common information for the web. When possible, existing formats, such as vCard (the standard format for contact details, supported by most address-book software and online services) and iCalendar (the standard format for calendar-based information, supported by most calendar software and online services) are used as the basis for a microformat—a practice that greatly aids interoperability between web-based content and applications and services.

Let’s look at an example in which we’ll use microformats to mark up contact details.

Adding Contact Details with hCard

Let’s start with contact details as they might be marked up without microformats:

In a few short steps, we’ll mark this up using the hCard microformat. hCard takes the semantics of the vCard specification and brings it to HTML, using the field names defined for vCard, but placing them inside HTML syntax. Here’s an example of the fields found in the vCard specification:

To turn that into HTML, we’ll use what’s called the “class design pattern” microformat. Make a note: This is the single most important pattern for microformat markup. Using the class design pattern, we’ll borrow the vCard field names and add them to HTML elements using the class attribute. For example, we would mark up the formatted name (the FN field in vCard) like this:

As you can see, we’ve simply taken the name of the field from vCard and added it as the value of the class attribute of the element that contains, in this example, the formatted name. We don’t have to add additional elements for each field: where there’s existing markup for a field, we can simply add to it.

Here’s how we’d take the earlier markup and turn it into hCard:

You’ll notice that in a couple of places, we had to add additional markup, because some of the needed elements didn’t exist. We’ve wrapped the region and locality information in span elements and then added the relevant class values to these. We’ve also added a div of class adr around the address markup, thus mapping the address details into the hCard microformat. Depending on the nature of your existing markup, you may or may not need to do this; your existing markup can usually remain largely as it is. Microformats don’t require you to drastically change your markup to support them.

Got Root?

“But,” you might be asking, “how does anyone know this is really an hCard microformat, not just a collection of elements with class values?” The answer is that we need to add one more bit of markup to finish the job of making this address microformatted using the hCard format.

Compound microformats, like hCard, that comprise more than one element, require a root element that contains all of the microformatted content. In this case, we don’t have an element that wraps up all our address details (though we will have one in many cases). For this example, we’ll add a div element to contain the address, and we’ll give it a class value of vcard to specify that what it contains is hCard-formatted content. (We use vcard rather than hCard because hCard is simply the vCard specification reformatted for HTML.)

And there we have it: our contact details marked up as an hCard. hCard also provides fields for URLs, email addresses, phone numbers, and fax numbers—all the kinds of things you’d expect from contact details—and all of these are marked up very similarly to the address here.

Microformats Tools

Over the four years or so since their inception, a vibrant set of tools for working with microformats has emerged (created by everyone from individual developers all the way up to major companies such as Microsoft and Yahoo). There are tools to simplify the creation of various kinds of microformatted content, services that ease the process of adding functionality to your microformatted sites, tools for “validating” microformatted content, and JavaScript-based tools for adding features to your microformatted sites. We list these at the end of the book, along with books and online resources for learning more about microformats.

Much, Much More

There’s a great deal more to microformats than this—indeed, I wrote an entire book on them in 2007 that is still highly relevant, and which, if you are keen to dive deeper, you may find very helpful. You can find a reference to it at the end of this book.

The Wrap

Web developers spend a lot of time focusing on users and user experience, but we rarely consider software and other developers as users of our sites. (This despite the fact that every time a site is visited, software in the form of a browser “uses” it.) And of course, search engines are perhaps the single most important user of any but the most private of sites—if a site’s content is hidden from search engines by bad coding practices, the consequences can be catastrophic.

In this chapter, we’ve looked at some of the needs of our software users and some of the techniques and practices we can use to take care of these needs. As an added bonus, these techniques also produce more readable code—and whether you are returning to your own code after weeks away or approaching someone else’s code for the first time, you’ll find that clean, readable, well commented code is far more maintainable and comprehensible than the other sort, and you’ll be thankful that you spent the time to make it that way.