I don't try to help everyone with their problem. It has to interest me, for one thing. Or, it has to be easy to spot the problem. The inverse is that if it's hard to make heads or tails of the markup, I'm likely to move on to the next post.

There are plenty of articles aimed at asking good questions, providing good information, having a good attitude, and et cetera. I'll be talking about some mechanical aspects.

This is the first of what should be two rants about formatting for ease of reading. This part deals with html formatting. Forget about so-called html optimization. The bandwidth savings due to squeezing out the white space, etc. are trivial compared to the savings you've already gained by dumping table based layout in favor of external stylesheets. What is not trivial is the importance of the code being easily read by the Mark I, Mod 0 human eyeballs.

Howto: Make it hard on helpers

The example below exhibits a couple of things that make a simple document source more difficult to read than it should be. The things done right are the consistent indention plan and the lack of large areas of unnecessary white space (superfluous linefeeds).

So what's wrong with it? For starters, the indention is created with tabs. Different editors and source viewers treat tabs differently, but most make the tab equivalent to eight spaces. In the example, there are seven levels of nesting. As you can see, there's nothing unusual about the document excerpt—in fact, it's a common construct. That seventh level is fifty-six columns over before the first character. Combine that with a sane line wrap at seventy-two columns, and …

The second major error is the lack of word-wrap. If you want my help, why would you make me scroll back and forth to read your source?

<html>
	<body>
		<div id="wrapper">
			<div id="header">
				<h1>Generic header</h1>
				<ul>
					<li>top level link blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah blah </li>
					<li>top level link
						<ul>
							<li>sublink</li>
							<li>sublink</li>
						</ul>
					</li>
				</ul>
			</div>      
			<div id="main">
				<h2>generic section header</h2>
				<p>content stuff</p>
			</div>
		</div>
	</body>
</html>

The simple things that make debugging easier

Your first task is to configure your editor to make tabs only two or three spaces/columns deep. Any more is wasteful of the limited width of the window. Second, set the editor to convert tabs to spaces before saving. No matter what another editor or the viewer does with tabs, a space is a space. Your formatting will look the same for everyone.

If your editor supports auto-indent in html mode, set the indent to the same number of spaces as you set for the tabs.

Set the word-wrap to a sane value. Anywhere from sixty-six to eighty columns is good. My preference is seventy-two; choose what you like.

One more little helper is the comment. When you open a div, there's usually an id or class token. When you close that div, you should add a comment to indicate which div it is you're closing. Else, it's easy to lose track among even well indented nests.

What does the above example look like with these rules applied?

<body>
  <div id="wrapper">
    <div id="header">
      <h1>Generic header</h1>

      <ul>
        <li>top level link blah blah blah blah blah blah blah blah blah
        blah blah blah blah blah blah blah blah blah blah blah blah
        blah blah blah blah blah blah blah blah blah blah blah blah
        blah blah blah blah blah blah blah blah</li>

        <li>top level link
          <ul>
            <li>sublink</li>

            <li>sublink</li>
          </ul>
        </li>
      </ul>
    </div> <!-- end header -->

    <div id="main">
      <h2>generic section header</h2>

      <p>content stuff</p>
    </div> <!-- end main -->
  </div> <!-- end wrapper -->
</body>
</html>

Notice the formatting plan. Each nested element is indented 2 spaces. Sibling elements are separated by an empty line. All in all, a format that makes it easy to follow the structure of the document.

What if your editor doesn't do tab to space conversion? Get a better editor. My choice is Emacs; it's ancient, but still the best text editor in the world. There are other lesser editors to which their adherants cling with religious fervor. Look around.

Won't change editors? There's one hope left, and that's HTML Tidy. Tidy will reformat your (x)html to follow all these rules according to the .tidy or .tidyrc configuration file.

OK, one rant down. Prettifying your html pretty is actually an important step toward efficient debugging. It'll makes it easier on yourself and much easier on the guy or gal trying to help you.

cheers,

gary