Writing and recognising good code

The first thing to say is that good code is simpler than bad code. However, lots of bad code gets written because the author doesn't understand how to take advantage of HTML. The word "author" here means either a person writing code or—more likely—software which generates code from another kind of document.

There are also some practices which have been used habitually and pass for good code but which nevertheless are practices we should avoid when writing good future-proof code.

Here's an example of a common construction which misses a trick:

While they look similar in a browser, there is something very different going on in the code:

In the code for list A we see a paragraph (denoted by <p> and </p> tags) which contains several items forced to stack up by using a break (<br>) tag, and each preceded by a dot created with a character entity reference—a bullet (•). The list items are also indented using another character entity, this time a non-breaking space ( ), or rather two.

This gives a visually clear list of bullet points, indented from the rest of the text. So far, so good.

Now let's see what list B looks like behind the scenes:

First, all the items are enclosed in a <ul></ul> tag, which tells us that it's an unordered list. Next, each individual item is enclosed in a list item tag—<li></li>. That's it.

So, if they both display in a similar way, what's the difference? To the reader; not much. But to the user's browser and to any other machine reading the code there is a great deal of difference—and to the human author creating and editing the code the difference is huge.

Really, the first list is a fake, there's no list inherent in the code, it just looks like one in a visual browser. And in order to create the impression of a list some otherwise meaningless code has been required. The only thing in the list which has any intrinsic meaning is the paragraph tag itself and, of course, the text.

The second list, however, is a list through-and-through. There's nothing in the code which does not act to enhance the content. Each item in the list is tagged as exactly that: a list item; and the whole list is enclosed in a tag which says what kind of list it is—in this case an unordered one. A visual browser knows that lists are indented and that unordered lists have a bullet dot before each item, so there's no need for the author (that's you and me) to do any of this work.

Another advantage to the author and editor is that the list is still clearly a list even when the raw source code is examined. This makes editing and checking the code much simpler.

But the advantages don't stop there. Let's say we want our bullet list to be a numbered list instead. All we need to do is change the <ul></ul> tags to <ol></ol>—an ordered list:

Nothing else has changed. We haven't typed in any numbers, and it's useful that we don't need to since it means we can easily add an item to the list at any point and let the browser software re-number the list:

And if we need to alphabetize a numbered list it's just a matter of dragging the items around, with no need to re-type any numbers:

Lists can be nested too, so we can have:

We simply put another well-formed list into an existing list item, between the <li> and </li> tags.

Try to do that with the code in the first example and things quickly get ugly:

It may look much the same in a visual browser but the code is dreadful and weighty, and if another item is added to the list all the following items would need to be re-numbered by hand. Not a good use of anyone's time! Neither have we added any more intrinsic meaning.

In short, taking advantage of proper HTML lists allows authors greater flexibility than simply creating lists using constructions like the first example, while also saving time and resulting in code which is clearer and more easily edited.

There are other kinds of lists too, and ways to make lists enumerated by letters, roman numerals, etc. but this is not a discussion of how to create lists—we're using them to demonstrate some principles of good HTML. We're showing how to break the curse of trying too hard—how to make life easier by applying a bit of the built-in cleverness of HTML.

At this point, the reader would be forgiven for thinking that the above examples of bad code are real horrors, but really they're mild by comparison. Validate this page's source code and they won't be flagged as errors; the examples are valid code which simply misses a trick. .

Heading the wrong way

Here's a real-life example of code which both misses a trick (or two) and fails to validate; a chunk of code and content found (15 June 2004) on a New Zealand Touch Rugby site:

This is quite lightweight coding—a good thing—but the code itself is not good. Let's take it apart:

First we find an opening font declaration with a class of "H2", which is followed by a line of text (in uppercase) wrapped in paragraph tags. The next line starts with an opening paragraph which is followed by the closing tag for the earlier font tag and then another opening font tag, this time with a class of "main". The next tags are the closing paragraph and the opening tag for the next paragraph. Last of all is the close tag of the last paragraph and the closing font tag for the one classed "main".

Now, I don't want to be too critical about this because Touch Rugby is an excellent sport, and some of my best friends are Kiwis. Also because I doubt a human actually wrote this code; any human capable of writing <font class="H2"> would also see straight away how stupid it is. (A quick look at the source code tells us where to point the finger ). The reason the code works at all on the site is because browser software is usually kind, generous and forgiving.

What is clearly intended here is that two paragraphs of text follow a heading, simple as that. But instead of tagging the heading as <h2></h2> it is tagged as a paragraph and then wrapped in a font declaration of class "H2"—in a misguided attempt to turn the paragraph into a heading. (We won't go into font declarations here since they're not something we should use in our code. Suffice it to say that the defining characteristic of a font declaration is that it declares a font. This example doesn't even do that.) Not only is it the wrong tag, but it's also in the wrong place. The tags are not nested properly—the closing </font> is inside the opening <p> of the next block.

The next font declaration—apart from not being properly nested—has the class of "main", which is intended to mark this text as the main text (perhaps so that a style can be applied). But here again we encounter the Curse of Trying Too Hard. Shouldn't the main text be the default? If we need to apply classes (and sometimes we do) then we should mark text which is not the main text.

The last point about this example is less clear-cut: the heading in uppercase (or block capitals). This is mostly a point about style which has little to do with HTML code, but there is a practical aspect too. Let's say the heading included and acronym or abbreviation—there would be no distinction between the uppercase word and the uppercase acronym. But more than that, it limits our flexibility when it comes to imposing a visual style on our text. If we want uppercase headings we can use a rule which tells the browser to display headings uppercase (or just <h2></h2> headings), so we have the freedom to change our mind without having to re-type the text.

The text of this heading is not uppercase

A rule has been set for this page which says that heading level <h3> should be displayed as uppercase, as in the above heading.

The source code looks like this:

To go back to the example we were just picking apart, if we follow good practice then it would be better coded like this:

It's a lot simpler and clearer, and has a logical structure which the original lacks.

Validate: XHTML CSS

This page was last updated when I had time.

All material in this web site which was originally created by me is © Philip King 2003 and licensed under a Creative Commons License.

These pages hosted by GreenNet.