Accessibility
 
 
Writing Structured Code
 By Al DiMarzio
HB Graphics
Guilford CT

The last thing anyone wants to do is to learn how to structure code. We would all rather be writing it and having fun. But the fun ends quite abruptly when you go back a few weeks later and you wonder who wrote this code. It happens to me and I've been writing code for 40 years. HTML, like Basic code, is easy to write and understand, and because of this, many Web designers tend to get sloppy ... myself included.

Working with other code developers exacerbates the problem as does the fact that quite a few of the current crop of WYSIWYG editors create almost incomprehensible code. To survive, we need to understand how to structure code to make it extensible and maintainable. There is no right or wrong way to do it. It's just a matter or organization. On one end of the spectrum, we have the proponents of "left justify everything," and on the other end we have the "let's indent everything." As with many things, a compromise seems appropriate: indent only when it makes the code easier to read.

But what makes code easy to read? To start with, we can group logical pieces of code and set them apart from the other groups of code. Then, within each group we indent lines of code which are subordinate to the code above it. Kind of like an inverted pyramid. The concept seems simple enough. Let's apply it to some sample code.

Table and Other Structures

For our beginning example, let's examine an HTML table. I suggest we assign the <table> and <tr> tags as equal partners and place one below the other. In truth, the <tr> tag is subordinate to the <table> tag. However, indenting the <tr> tag would, in my opinion, create too many levels of indents ... especially when you have nested tables. The table data <td> and table heading <th> tags are subordinate to the <tr> tag, so let's indent them. This is how it might look with heading and data tags: 

	
<table border="0" cellspacing="0" cellpadding="0">
	<tr>
		<th>Heading One</th>
		<th>Heading Two</th>
		<th>Heading Three</th></tr>
	<tr valign="top">
		<td align="center">Items under heading one.</td>
		<td>Next column of information.</td>
		<td>Last column of text.</td></tr>
	</table>
Please notice that I put the closing </tr> tag next to the last <th> and </td> tag. This makes it easier to read down the left side of the code and see the main segments. And besides, why take up a whole line of code just for a </tr> tag. The </table> tag is brought to the left forming a 'block' of the table code. Don't worry about loosing a </tr> tag. You will of course validate your code. HomeSite has a great code validator ... use it often.

With small chunks of code, whether or not to indent is not so obvious. Tags such as <font>, <div>, and <map> could be placed on a single line or in a group. Either way the code is readable, and that is what's important.

	<div align="center">Title for the page</div>
Code groups such as the following might take on a different structure. Note how the </div> and </table> tags form indented blocks of code. 

<div align="center">
		<table width="375" border="0" cellspacing="0" cellpadding="10" 
		bgcolor="#dddddd">
		<tr>
			<td>this is a line of text.</td></tr>
		<tr>
			<td>and a second data cell with text</td></tr>
		</table>
	</div>
On the other hand, depending upon personal preferences, you could align the <table> tag under the <div> tag which would reduce the indents by one and create a more solid "block" effect. The important thing is to pick a style and stick with it. Consistency and readability are the key factors at work here.

Some code tags readily lend themselves to creating blocks such as the image map group shown below.

<map name="Map">
		<area shape="rect" coords="100,255,200,285" 
		href="javascript:seeItAgain()">
		<area shape="rect" coords="200,255,300,285" href="intro.htm">
<area shape="rect" coords="300,255,400,285" href="main.htm">
<area shape="rect" coords="400,255,500,285" href="other.htm">
</map>
The whole point of this discussion is to create readability by combining like functions and separating groups of code. I don't see the need for a whole set of rigid rules. Pick what works for you and your group and stick to it. But as you will see in a later example, I break my own rules when I think it will increase readability.

A Few Additional Thoughts

While we are discussing structuring code, allow me to bring up a few code-related topics that you may or may not have encountered.

XML is a highly structured language, and its increasing acceptance in Web-page creation will necessitate a structured design approach. The books call it "well formed" code, and unlike HTML browsers, the XML-enabled browsers will not attempt to fix bad code on the fly. If XML is not well formed, you will receive error messages ... period. Part of the problem with present-day HTML browsers is that each interprets and repairs HTML code differently.

XML requires that all tag attributes be in quotes whereas HTML does not care if they are quoted or not. I recommend that you always quote your attributes. Get ready for the next wave of Web development languages.

While putting tags on separate lines creates a structured look, sometimes the browsers interpret the 'invisible' characters, such as line feeds, even though they are supposed to be ignored in HTML. For example, the following lines contain the same code but may appear differently, depending upon your browser:

Concatenated code :

<img src="this.gif" width="100" height="50" border="1"><img src="that.gif" width="100" height="50" border="1">
Code with editor invisible line feed after first line of code: 

<img src="this.gif" width="100" height="50" border="1">
<img src="that.gif" width="100" height="50" border="1">
You would think that in both instances the images would appear side by side. However, the latter example could show a slight space between the images. Here is a case where neat structure can work against you. One method of controlling page content is to use gutter columns, created using empty <td> tags, to horizontally space text and/or images. Also, the use of the <td> tag height attribute can be used to create vertical spaces in pixel increments. Often a full <br> tag is too much, and no line space is too little. These topographical nuances make for a better looking page, and I don't mind the extra coding.

Sprinkle your code with comments to show the flow of information, any browser workarounds, and the identification of the page sections. You might be surprised just how often comments are worth their weight in gold pixels one week after you wrote the code.

One last thought. If you don't specify the border, cell padding, and cell spacing attributes in a table tag, it doesn't set those parameters to zero as you might expect. So specify them as "0" if you want tight tables.

Practical Example

Okay, let's put all these things together in the example shown below:

Figure 1: Practical example.

The overall page table uses gutter columns to keep the text off the edge of the browser and colored table data to create a side-bar effect.

Please note that code groups are set apart with extra line spacing. Also, each <br> line break tag, which creates a line space in HTML, should be on a separate line. This helps in reading the code and finding unwanted spacing in the page.

In a few instances, the </td> tag hangs out to the left, but only when the table data contains a quantity of code such as other tables. This breaking of the rules makes the code more readable, and that is what this is all about.

When the document's text wraps to the next line, it disrupts the structured flow of the code. Unfortunately, there isn't much you can do about it that won't cause more grief than it cures.

Here's what the code behind the example page looks like:

------------------ Begin code snippet ----------------

<table width="600" border="0" cellpadding="0" cellspacing="0">
<tr>
	<td width="10"></td>  <!-- Left side gutter column -->
	<td>
	
	<!-- Begin content portion of the page -->
	<table width="580" border="0" cellpadding="0" cellspacing="0">
	<tr>
		<td width="580" colspan="3">

		<!-- Structured approach to making the header-->
		<div align="center">
		<font face="Arial,Helvetica,sans-serif" size="-1" color="#800000">
			<b>TWO EQUAL-COLUMN DISPLAY OF DATA</b>
		</font>
		</div>

		
		You may not notice that the left and right sides of this page have 10 
		pixel margins. They are created using table data and prevent the text 
		from banging against the page sides.</td></tr>
	<tr>
		<td height="6"></td></tr>  <!-- Vertical 1/2 spacing -->
	<tr>
		<td width="285">When you are making a two column spread it is a 
		good idea to specify the column widths of all the table data. Otherwise 
		the browser defaults may do something strange.</td>
		<td width="10"></td>
		<td width="285">Placing a gutter column to the left, such as we 
		do here, makes for easier reading and keeps nice text spacing regardless 
		of how the text lies within the column.</td></tr>
	</table>
	
	<table width="580" border="0" cellpadding="0" cellspacing="0">
	<tr>
		<td width="580" colspan="3">
		<br>

		<!-- Unstructured approach.  -It is hard to debug code in this mess. -->
		<div align="center"><font face="Arial,Helvetica,sans-serif" size="-1" 
		color="#800000"><b>TWO UNEQUAL WIDTH COLUMN DISPLAY OF DATA</b>
		</font></div>When you want to create multiple columns or column widths 
		that are different from a preceding section, it is best to begin a new table. Keeping 
		track of column spans can be confusing.</td></tr>
	<tr>
		<td height="6"></td></tr>
	<tr valign="top">
		<td width="450">
<img src="orvieto_duomo.jpg" width="121" height="117" alt="" border="1" 
align="left" hspace="8">
Here we have a wide column with an image. Use the align left attribute of the 
image tag to wrap text around the image, and use the hspace attribute to create 
some air around the image.<br>
		<br>
		<br>
		<br>
		
		<div align="center">
		<table width="375" border="0" cellspacing="0" cellpadding="10" 
		bgcolor="#dddddd">
		<tr>
			<td><b><i>This is a neat little trick to add a highlight in the 
			middle of a page to call attention to a specific point.
			</i></b></td></tr>
		</table>
		</div>
		
		</td>  <!-- Moved to the left to denote the end of a 
		code-filled table data. -->
		<td width="10"></td>
		<td width="120">
		
		<table border="1" cellspacing="0" cellpadding="5" bgcolor="#ffffee">
		<tr>
			<td align="center">
			<font face="Arial,Helvetica,sans-serif" size="-1">
				<br>
				One<br>
				Two<br>
				Three<br>
				Four<br>
				Seventeen<br>
				Twenty<br>
				<br>
			</font>
			</td></tr>
		</table>
		
		</td></tr>
	</table>
	<!-- End of content portion of the page. -->	

	</td>
	<td width="10"></td></tr>  <!—Right-side gutter column. -->
</table>

------------------ End code snippet ----------------

So, What's it All About

While there are always trade-offs in structuring code, the goal is to create repetitive groups that form blocks and are easily read. Consistency in structure facilitates identifying problem areas and maintaining code.

When I develop Web page code, I mainly use HomeSite. The easy-to-use code structure and tag color identification scheme facilitates development, as do its code-assisting wizards. Sure, I know HomeSite is Allaire's product and this is their Web site, but after coding HTML for years using all kinds of editors, I like this one the best. I also use Macromedia's Dreamweaver to create some of the initial code and image placement. Their layers option is a great design tool. Additionally, HomeSite and Dreamweaver allow me to work back and forth almost seamlessly on a Web page. The final page, however, is always completed in HomeSite and validated there.

If you understand how code should be structured, you can work in teams without confusion; you can maintain your code more easily, and you can debug it faster with less pain. Write your next project using these structured code ideas. You'll feel better in the morning.

About the Author

Al DiMarzio's career and business interests in computing technologies, marketing, and publishing span more than 40 years. In a lifestyle change, Al left the corporate world and formed HB Graphics. The company, primarily desktop publishing, move quickly into Web publishing in 1995 and grew from static HTML to interactive, data-driven Web sites.

Al received a BSEE and MSEE from Northeastern University and has completed corporate and post-graduate studies. During his tenure in engineering R&D, he received three patents. He has authored more than 50 articles and reports on computing technology, business management, and marketing, and has conducted seminars on the same topics.

Al can be reached by email at dimarzio@hbgraphics.com, and his Web site is accessible at http://www.hbgraphics.com/.