HTML Code Guidelines

3. HTML Code Guidelines

3.1 Directory Structure & Naming Conventions
3.2 General Tag Formatting Conventions
3.3 Commenting Conventions
3.4 Miscellaneous Conventions
3.5 Tag-Specific Format Conventions
3.6 Unused Tags (depricated, legacy)
3.7 WYSIWYG Code Generation

3.1 Directory Structure & Naming Conventions

3.2 General Tag Formatting Conventions

In accordance with the W3C (World Wide Web Standards Committee), The Onaicul Project has adopted the following HTML code outline. The intent of this outline is to ensure browser compatibility with all HTML code as well as to preserve consistency between and within projects. The outline should be adhered to as strictly as possible whenever possible. That said, it is also noted that engineers may compromise components of the outline when necessary to improve readability, functionality, and/or consistency.

Although every company probably has different HTML standards, it is important that everyone at The Onaicul Project write it the same way. The following are some of the style guidelines for writing HTML:

All tags are lowercase (NOT CAPITALIZED). Your favorite HTML editor should be customizeable (Options>Settings>General) so that the automatically inserted tags are lowercase. In keeping with the new W3C recommendation for standardized and forward compatible HTML code we are asking that you try and keep all tags lowercase.

When describing parameters of an image, use quotation marks around all numbers. Always include the WIDTH and HEIGHT tags (to improve the load time of the page), and include BORDER=”0” particularly when the image is a link (some browsers will default to putting a 1 pixel blue border around any hot image if the parameter is not set to zero). ALT tags can be very useful for describing the Content of that image so that if the image doesn't load, at least the audience will know what the image is about (what it links to, etc).

3.3 Commenting Conventions

The following commenting conventions should be used when writing code:

Format

The HTML commenting tag uses the following format:

<!-- Comment Goes Here //-->

Comments may span more than one line. As long as the tag begins with <!-- and ends with //-->. It is also a good idea to put any code within the <script> tags within comments. This is done because to avoid older browsers displaying the (javascript) code on the page.

Code

All code should be thoroughly commented. Comments should be used to provide explanations of logical code blocks. As a general rule, any group of code which is indented/nested should include a comment describing the code. In most cases, comments should not take up more than one line. All comments should be descriptive enough to provide a basic explanation of what the code does.

Unnecessary Comments

Lines of code which have been commented out for testing or re-writing purposes should be uncommented or removed in the finished product.

3.4 Meta Tags

META tags are a subset of the document header tags that allow people and machines that search and index the internet to see a short description and list of keywords related to the Content of your page.

It is strongly recommended that all Onaicul Project websites include meta tags. META tags are especially important when your site pages have little or no user-oriented text.

3.5 Tag-Specific Format Conventions

eg.
	Resized Window displaying only 80 Characters per line

Paragraph Tags

Paragraph Tags should be used very sparingly to ensure ease in readability.  All Paragraph Tags should be specified on a new line. Additionally, all Content within Paragraph Tags should be indented to emphasise the Paragraph Tag's domain.

Where possible, each section within a document should only contain one HTML Paragraph Tag set (" <P> ", " </P>"). When line breaks between paragraphs are necessary, two HTML Line Breaks (" <br><br> ") should be implemented in place of Paragraph Tags.  The exception to this rule is when a section of HTML Text is separated by a "Non-Paragraph-Text" object.

Ensure that all elements nest. Most browsers won't care if you overlap elements, but it is probably a good idea to try to keep to this rule. Newer versions of HTML require that you nest alll tags correctly. You should unclose the tags in reverse order - i.e. last opened - first closed.

3.6 Unused Tags

Obsolete tags (also known as Unused Tags or Depricated tags) can be harmful to a website. There are certain tags that were really popular in early versions of HTML that have since been modified or ommited from more recent W3C specifications.

It is a rather tedious process to list all of the unused tags, so instead I'll list some good resources to learn more about which tags form part of the current recomendations. The most recent W3C reccomendation will always have the final word on what is and isn't HTML.

Sizzling HTML by Jalfrezzi has an excellent resource that lists all the current valid HTML tags and their corresponding support in different browers at <http://vzone.virgin.net/sizzling.jalfrezi/frames/findex.htm>
"A comprehensive guide to writing web sites." -- http://vzone.virgin.net/sizzling.jalfrezi/  Text Only Version

To this day Kevin Werbach's "Bare Bones Guide to HTML" remains the essential quick-reference tool for HTML developers. Make sure you don't forget to download the handy text-only version and keep it somewhere on your hard disk for quick reference ;)

Brian Wilson has painstakingly created a fully functional online HTML reference manual. This is an absolute must to bookmark. You can also download a zipped version of the entire reference. Years from now you will still remember "index DOT html".

3.7 WYSIWYG Code Generation

The proliferation of HTML and the explosion of the World Wide Web has resulted in a parallel explosion and proliferation of WYSIWYG (What You See Is What You Get) editors that generate HTML and JavaScript. Although at first glance these editors seems to take some of the time out of HTML layout and production, in reality they often wind up costing more development time in the long run.

HTML Editors that do not allow personalization to the detailed level should be avoided. Redundant and unnecessary code, overcomplicated table structures, unformatted and incomplete tag and attribute statements, and poor nesting formats are just a few of the many problems these editors can introduce into code.

Still, advantages exist in using a professional WYSWIG editor when you know what you are doing. Dreamweaver by Macromedia stands out as one excellent example of a fully customizable robust HTML editor. It can be customized fully to produce code exactly how you like it. Online, resources like Webmonkey have devoted time to discussing different WYSIWYG editors.

HTML Code Example

Here is an example of proper HTML Code in compliance with the proposed code guidelines.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>xhtml</title>
<meta http-equiv="Content-Type" 
content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#F2E9DB" text="#000000" link="#CC3333"
vlink="#6699CC" alink="#FF6633">
<table border="0" cellpadding="0" cellspacing="0">
	<tr>
		<td valign="top" bgcolor="#F5F5F5">
<h1>Advantages of XHTML</h1>
<h2>The Extensible Hypertext Markup Language</h2>
<h3> What is XHTML?</h3>
<p> XHTML 1.0 became an official W3C recommendation on 
 January 26, 2000. A W3C Recommendation means that the 
 specification is stable, that it has been reviewed
 by the W3C membership, and that the specification 
 is now a Web standard.</p>
		</td>
	</tr>
</table>
<hr />
<p><font size="2">
<b>Last Modified</b> :
<script type="text/javascript" language="javascript">
<!--
document.write(""+document.lastModified+ "")
-->
</script> 
<br />
Author: <a href="http://www.onaicul.com/">
The Onaicul Project</a></font></p>
</body>
</html>

View this example code in your browser

Validate this page against it's DOCTYPE
Validation by WDG HTML Validator

     DOCTYPE: Document Type Declaration

Every HTML document must have a Document Type Declaration. This means exactly what it sounds like: a Document Type Declaration declares the document to be of a specific type. In our case this type is HTML.

     HTML: <html>

The first element will always be the HTML element. All HTML documents have an HTML element, which contains all the other elements. The HTML tags should (as well as all other tags) should always have a closing tag: </html>

     Head: <head>

The difference between the head and body of a document is that the head contains mostly information about the document, while the body contains the document itself. Scripts, stylesheets and meta tags all normally go within the <head> tags with some exceptions.

     Title: <title>

The TITLE element is a very simple element. It cannot contain anything but text and that text is the title of the document.

     Meta: <meta>

HTTP-Equiv: The browser or HTTP server uses this information to process the document. Some HTML editors add this tag automatically. It is a good idea to include it in all your documents (just like the DOCTYPE declaration). In this case the code is telling the browser that it is an HTML/TEXT document in iso-8859-1 encoding.

     Body: <body>

The Body tag holds alot of power over an html document. Without this tag the page WILL NOT WORK!
One mandatory attribute for the body tag is the page's background color or bgcolor. If a page is missing the bgcolor tag it will show up with a grey background on several browsers. It is also a good idea to set your text , link, alink and vlink tags. These tags allow you to specify the colors for the different kinds of text in your documents: text color, link color, active link and visited link, respectively.

     Table: <table>

The table tags should always be closed. Cellpadding, cellspacing, and border are all good attributes to include.

     Header 1 : <h1>

Visual browsers typically render H1 in a large, bold font. Authors can suggest a presentation for H1 through style sheets. The heading level should be chosen based on the heading's importance and placement in the document. An H1 is typically used as the main heading for a document.

The H1 element defines a level-one heading. A document generally should have exactly one H1 element to mark the most important heading.

The H2 element defines a level-two heading. This heading is more important than an H3 but less important than an H1.

The H3 element defines a level-three heading. This heading is more important than an H4 but less important than an H2.

     Paragraph : <p>

The P element defines a paragraph. The closing tag for P is optional, but its use prevents common browser bugs with style sheets.

HTML does not specify a presentation for the P element. Visual browsers commonly use block paragraphs with no first-line indent and separated by a blank line, but some browsers allow the user to specify a different presentation. An author can suggest paragraph indentation and spacing using style sheets.

P in W3C HTML 4.0 Recommendation

     Horizontal Rule : <hr />

The HR element defines a horizontal rule for visual browsers. While this element is inherently presentational, it can be used structurally as a section divider. It is always good form to close an element. Empty elements must either have an end tag or the start tag must end with />. (<br /> should be closed as well.)

     Font : <font>

The FONT element, deprecated in HTML 4.0 in favor of style sheets, allows authors to suggest rudimentary font changes. Use of the FONT element brings numerous usability and accessibility problems, as discussed in the article Font Face Considered Harmful?

     Bold : <b>

The B element suggests that text be rendered as bold text.

     Script : <script>

The SCRIPT element includes a client-side script in the document. Client-side scripts allow greater interactivity in a document by responding to user events. For example, a script could be used to check the user's form input prior to submission to provide immediate notice of any errors by the user.

§ Further Reading §