One of the easiest ways to keep your code easy to update, read, and debug is to keep it neat. That means indentation, documentation, consistency, and logic need to be applied. These are basics in any programming class, and they are just as applicable with coding HTML as they are with C++ or any other programming language.

Indentation

Indenting your code, usually by a tab or with spaces, makes it much easier to read because you can tell what sections are inside others (i.e. what is a child and what is a parent). Example of ugly, unindented code:

1
2
3
4

<div id="head"><div class="title">My page <img src="john.gif" alt="My Page"></div>
<a href="http://www.google.com/">Google <b>is great</b>
   </a></div><div id="main"><p>My
stuff</p></div>

Now because that’s such a short segment of code, it’s easy enough to look and understand. However, if you have 300 lines or so of stuff like that, you’re going to get a headache and you might miss some otherwise obvious errors that you’re trying to correct. Example of cleaner, indented code:

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

<div id="head">
  <div class="title">
    My page
    <img src="john.gif" alt="My Page">
  </div>
  <a href="http://www.google.com/">
    Google <b>is great</b>
  </a>
</div>
<div id="main">
  <p>My stuff</p>
</div>

Now it’s easy to tell that the “title” class is nested inside the “head” ID, and that “head” and “main” are separate. In the future, if I edit this code and the page no longer displays how I want it to, it would be a simple thing to come back and realize that I must have left out a closing </div> or didn’t put my “footer” ID outside of the “main” ID, because of how the spacing lines things up.

HTML isn’t the only thing you should indent: CSS is a prime candidate for indentation. Example of ugly CSS arrangement:

1

body {font-family: "Verdana", sans-serif; background-color: #fff; color: #000; line-height: 130%; font-size: small; margin: 0;}

And here’s that same code, neatly indented with tabs and organized:

1
2
3
4
5
6
7
8

body {
  margin: 0;
  background-color: #fff;
  color: #000;
  font-family: "Verdana", sans-serif;
  font-size: small;
  line-height: 130%;
}

I have a tendency of indenting entire sections if, within the HTML, they are subsections. Example:

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

#head {font-size: 150%;}

  #head div.title {
    font-size: 90%;
    color: #494949;
    border: 1px solid #999;
  }

#main {
  font-size: 80%;
  font-family: "Georgia", "Times New Roman", serif;
}

Since the “title” class is within the “head” ID in the HTML code, I indent the styling for the “title” class so that it looks to be a child of “head”.

It’s really not hard to keep up good indentation practices, especially with the help of a good editor. I recommend Bluefish, Vim, or Dreamweaver.

Documentation

The next step in making your code more readable is to explain things that might otherwise be obscure. A habit of mine is to note which <div> is ending when I put in the closing tag, if the tag is not on the same line as the opening tag. Example, using the above code:

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

<div id="head">
  <div class="title">
    My page
    <img src="john.gif" alt="My Page">
  </div><!--End of class title-->
  <a href="http://www.google.com/">
    Google <b>is great</b>
  </a>
</div><!--End of ID head-->
<div id="main">
  <p>My stuff</p>
</div><!--End of ID main-->

Again, this may not seem necessary for this small bit of code, but when you’re dealing with several <div> tags that are nested within each other and mixed in with other code, this can be very helpful. Without such comments, you might remove the wrong closing tag for a <div> that you don’t want removed. I don’t comment the opening tag because it isn’t necessary: the class and id attributes are explanation enough.

Other useful documentation can be to explain what a particular section is for, if it isn’t already clear:

1
2
3
4
5

<!--This will hold the date and time that I last updated-->
<div class="dtlastUp">
  06.23.05 - Thursday<br>
  3:12 P.M.
</div>

Documentation is especially important if someone else is going to be looking at your code. If you’re running an art collab with a friend and you each have your hands in the source, you don’t want to be left baffled by their wacky coding, wondering why on earth she used an inline <h1> rather than just a <span>.

Consistency

Neat code is consistent. Don’t start out indenting with a space and halfway down the page indent with a tab. If you put comments describing the appearance of each <div> tag on one page, do it for the other pages. With your CSS, if you start having the opening bracket on the same line as the body section, then keep it on the same line for all the sections. If you make your main header be a <div> of a specific class and not an <h1>, then make all the main headers of all your pages use that <div> with its specific class.

Having code that is consistent in its appearance makes it easier to debug. If a page isn’t showing up correctly and you’ve coded the page in a neat fashion, consistent with spacing and the naming of things, then it might be possible to find the error with a cursory glance at the code. You won’t have to weed through pages of a jumbled-up mess in order to find that you didn’t close that <table> like you thought you did.

Logic

The most illogical thing I see in web design is the misuse or bizarre usage of different tags. Just because you can make a page look pretty by using nothing but the <span> tag and some wild CSS doesn’t mean that that’s the best option. The following are some common oddities:

Lists

If you want a list of items, use either <ul> or <ol>; don’t just make a list of items separated by <br>’s. You have more control over your content if it is in a list than if you just have a bunch of lines and breaks. For example, using CSS you can change the bullet image, the line-height, borders, colors, fonts, whether the list is displayed inline or one item per line, padding, margins, and so on. If you just have things separated by the <br> tag, then you’re going to have stuff all that into another area, perhaps a <div> or a <p>, and use CSS to style that to get the same effect. And as for bullets or numbers or images alongside each item, well, now those you’ll have to put in by hand. With <ul> and <ol>, they’re there by default.

Paragraphs

There is no need to have a block of text separated by two <br> tags to create the look of a paragraph. There is a specific tag for this: the <p> tag, and she is your friend. Use her! I have no idea why people want to use <br>’s for this purpose. They are intended to create a line break, which is not the same as ending a paragraph. Maybe because having two <br>’s generally makes a larger space than just closing and opening a <p> tag. That’s something that is easily changed with CSS:

1

p {margin: 15px 0;}

That will make it so that there is a margin of 15px above and below each <p> tag. You can change that to 150px for all CSS cares. See? The <p> tag offers you more flexibility, which is always a good thing.

Tables

The purpose of tables is to hold tabular data, like the billing records from the month of April for a few customers. Tables are a poor way of designing a layout, but it’s done all the time. Using <div> tags and some CSS (mainly the float property) is preferable. One reason this is so is because tables don’t resize worth a two-dollar whore. If you specify a table width because your layout’s main image is 847 pixels wide and I resize my browser to be only 842 pixels wide, then I’m going to get a horizontal scrollbar and that’s annoying. However, if you use <div> tags with some CSS, you can have it so that the sections of the page either resize with the browser, get cut off at a certain width, or flop down to a different position on the page. All of those keep that horizontal scrollbar from appearing.

More information related to this can be found in HTML Dog’s Mastering Text article.