Приглашаем посетить
Чулков (chulkov.lit-info.ru)

Writing Maintainable HTML Code

Previous Page
Table of Contents
Next Page

Writing Maintainable HTML Code

If you've ever done any programming, you already know how important it is to write code that can be maintained. If you don't have any programming background, understand that what I'm talking about is the ability for you or someone else to look at your code later and not be utterly confused by it. The challenge is to make your code as immediately understandable as possible. Trust me, there will come a time when you'll look back on a page that you wrote and you won't have a clue what you were thinking or why you wrote the code the way you did. Fortunately, there is a way to combat this problem of apparent memory loss!

Documenting Code with Comments

Whenever you develop an HTML page, keep in mind that you or someone else will almost certainly need to make changes to it someday. Simple text web pages are usually fairly easy to read and revise, but complex pages with graphics, tables, and other layout tricks can be quite difficult to decipher.

To see what I'm talking about, visit just about any page in a web browser and view its source code by clicking the View menu followed by Source (Internet Explorer) or View and then Page Source (Firefox). You'll likely see a jumbled bunch of code that is tough to decipher as pure HTML. This largely has to do with the fact that the code for large commercial web pages is generated dynamically by content management software systems, and is therefore more cryptic in structure. For the sake of maintaining your own pages, I encourage you to try to impose a little more order on your web page code.

As you saw in Hour 17, "Web Page Scripting for Nonprogrammers," you can enclose comments to yourself or your co-authors between <!-- and --> tags. These comments will not appear on the web page when viewed with a browser but can be read by anyone who examines the HTML code with a text editor, a word processor, a web development tool, or a web browser's View Source command. The following example provides a little refresher just to show you how a comment is coded:

<!-- This image needs to be updated daily. -->
<img src="headline.jpg" alt="Today's Headline" />

As this code reveals, the comment just before the <img /> tag provides a clue as to how the image is used. When someone reads this code, they know immediately that this is an image that must be updated every day. The text in the comment is completely ignored by web browsers.

By the Way

To include comments in a JavaScript script, put // at the beginning of each comment line. (No closing tag is needed for JavaScript comments.) In style sheets, start comments with /* and end them with */.

The HTML <!-- and --> tags will not work properly in scripts or style sheets!

You can and should, however, include one <!-- tag just after a <script> or <style> tag, with a --> tag just before the matching </script> or </style>. This hides the script or style commands from older browsers that would otherwise treat them as regular text and display them on the page.


Did you Know?

One handy usage of comments is to hide parts of a web page that are currently under construction. Rather than making the text and graphics visible and explaining that they're under construction, you can hide them from view entirely with some carefully placed comments. This is a great way to work on portions of a page gradually and show only the end result to the world when you're finished.


Try It Yourself

It will be well worth your time now to go through all the web pages, scripts, and style sheets you've created so far and add any comments that you or others might find helpful when revising them in the future. Here's what to do:

1.
Put a comment explaining any fancy formatting or layout techniques before the tags that make it happen.

2.
Use a comment just before an <img /> tag to briefly describe any important graphic whose function isn't obvious from the alt message.

3.
Consider using a comment (or several comments) to summarize how the cells of a <table> are supposed to fit together visually.

4.
If you use hexadecimal color codes (such as <div style="color: #8040B0">), insert a comment indicating what the color actually is (bluish-purple).

5.
Indenting your comments helps them stand out and makes both the comments and the HTML easier to read. Don't forget to use indentation in the HTML itself to make it more readable, too.

Indenting Code for Clarity

I have a confession. Throughout the book I've been carefully indoctrinating you into an HTML code development style without really letting on. It's time to spill the beans. You've no doubt noticed a consistent pattern with respect to the indentation of all the HTML code in the book. More specifically, each child tag is indented to the right two spaces from its parent tag. Furthermore, content within a tag that spans more than one line is indented within the tag.

The best way to learn the value of indentation is to see some HTML code without it. You know how the song goes"you don't know what you've got [']til it's gone." Anyway, here's a very simple table coded without any indentation:

<table>
<tr><td>Cell One</td>
<td>Cell Two</td></tr>
<tr><td>Cell Three</td>
<td>Cell Four</td></tr>
</table>

Not only is there no indentation but there also is no delineation between rows and columns within the table. Now compare this code with the following code, which describes the exact same table:

<table>
  <tr>
    <td>Cell One</td>
    <td>Cell Two</td>
  </tr>
  <tr>
    <td>Cell Three</td>
    <td>Cell Four</td>
  </tr>
</table>

This heavily indented code makes it plainly obvious how the rows and columns are divided up via <tr> and <td> tags.

In my opinion, consistent indentation is even more important than comments when it comes to making your HTML code understandable and maintainable. And you don't have to buy into my specific indentation strategy. If you'd rather use three or four spaces instead of two, that's fine with me. And if you want to tighten things up a bit and not indent content within a tag, I don't have a problem with that. The main thing to take from this is that it's important to develop a coding style of your own and then ruthlessly stick to it.

Did you Know?

If you work with other people or plan on working with other people developing web pages, you should consider getting together as a group to formulate a consistent coding style. That way everyone is on the same page, pun intended.



Previous Page
Table of Contents
Next Page