Drop Shadow

Web programming style guide

Where they can apply, the programming style guidelines also apply to HTML, CSS, and XML. For example, both the indentation guidelines and the line endings guidelines must be followed for HTML, CSS, and XML.

Using correct indentation and informative class names will make it easier for other people to understand your pages. They will be able to come up to speed more quickly when you need other eyes on the design or when you aren’t available and changes need to be made.

Steps to designing a web page

Design your web pages to standards, so that they are available to a wide audience and so that they remain available in the future as browsers evolve.

Design the structure first

When you design a web page, design the structure first, without any CSS or Javascript. Do not use HTML formatting options; you’ll use CSS in the next step to modify formatting. Design and discover the underlying structure of the page. Make sure that you use headlines for headlines, lists for lists, paragraphs for paragraphs, and so on. You won’t need any DIVs at this step, but make sure that the HTML elements have the correct parents and children.

Do not think about formatting. You want to discover the hierarchy of the elements in this page or template.

Design the style sheets

After the structure has been created and approved, create the static styles. Write to standard CSS first—don’t add any hacks or tricks to get the styles to work in browsers that don’t adhere to standards.

You may need to add DIVs to mark sections of the document. Your class names and IDs must never reflect the expected formatting. Their names should reflect the underlying purpose of that section or part of the page.

Always understand why you are doing something. Be especially wary of arbitrary numbers for margin and padding.

Do not use pixels or points

Do not use pixels, points, or any hard-coding to layout the page at this point. Hard-coding sizes to pixels and points does not just specify a size, it specifies a technology, and blocks visitors who are not using that technology. All sizes should be em-widths (if they are related to the size of the text in the visitor’s browser) or percentages (if they are related to the size of the parent element).

Keep definitions simple

Remember that we want to make sure that we can easily edit and understand these files later. When there are common style definitions, they should be combined in one place instead of having the same three font families spread in five or more places throughout the style sheet. It also means specifying only the relevant tags in the hierarchy instead of the entire hierarchy.

If what differentiates a style is that it’s in a span of class “professor”, then all we need is span.professor, not body#landing table.listing.display tbody tr td p span.professor. If what differentiates it is that it’s a span of class “professor” on a page with body id landing, then all we need is body#landing span.professor.

Otherwise, it’s harder to see what’s relevant, and it’s harder to customize later, because the more tags you have in a definition the higher its precedence. By only specifying what’s relevant, precedence becomes nearly automatic. That is, where what’s relevant is “span.professor”, all span.professors get those styles; where what’s relevant is “body#landing span.professor”, only span.professors in body#landing get it. It reduces the number of definitions needed (no need to create a definition for each page type if the styles will be the same) and increases flexibility.

Dynamic and printing styles

After the static styles have been approved, create any dynamic styles such as hovers.

If there will be any modifications to the styles for printing, create the print style sheet now. The print style sheet should build on the overall style sheet.

Add non-standard browser hacks

Once the page is correctly designed, you may need to add support for browsers that don’t support CSS standards. Put these changes in a separate style sheet. Where possible, segregate these style sheets from browsers that do adhere to standards. For example, when adding extra styles to Internet Explorer, use comments and the IE scripting language to add hacked CSS just for IE:

<!--[if lte ie 7.000]> <link href="/css/ie.css" rel="stylesheet" type="text/css" /> <![endif]--> <!--[if lt ie 7.000]> <link href="/css/ie6.css" rel="stylesheet" type="text/css" /> <![endif]-->

Never use hacks in the main style sheets.

Add extra features

After the style sheets have been created, add JavaScript to aid the visitor, but ensure that JavaScript is not required to view the page.

At this point, if we need to hard-code the page to a specific width, change just the body width in the style sheet. However, consider that by doing this, you’re locking out people with sight problems (who want to make it larger), people with portable browsers (who want to make it smaller) and people with needs you haven’t thought of. A flexible design will mean a better browsing experience for more visitors, at the same time that it makes the web site more reliable when we make changes later on.

Locking pages down tends to become a vicious cycle where you see people doing things to your web page that you don’t like, so you lock that down, too, and then they come up with a way around that, so you restrict them further, until your web page is locked down to the point that you are the only visitor it is appropriate for.

Undocumented features

An undocumented feature is not a feature, it’s a bug. Avoiding undocumented features is especially important for HTML, CSS, and JavaScript. If something later stops working on server-side code, we’ll find out quickly enough. But if something stops working in client-side code, it will stop working for some people but not others, in some browsers but not others, with some settings but not others.

Where does functionality belong?

Web page content is always created in HTML, with visual styles defined in CSS. JavaScript can be used to enhance the user experience, but cannot be used to display content.

Never use client-side JavaScript to implement security; use server-side code for this. Remember that JavaScript, HTML, and CSS are all under the control of the browser.

Do not create servants’ entrances for alternative browsers; display once in a standard format.

Appropriate use of images

Images should never contain text. Resist the urge to create on-line documents as if they were print documents; they aren’t. Print documents are displayed in a single format on a known technology—a piece of paper of a specific size, color, and matte. On-line documents need to be displayed on many different technologies with many different specifications.

While alt tags are useful for describing the content of an image, they should not be used to create servants’ entrances; invariably, some of the servants’ entrances fall out of sync with the real content. Don’t repeat yourself!

Appropriate use of JavaScript

Critical content must always be viewable without JavaScript and without having to enter the information twice. JavaScript can be used to enhance content display, but must not be required to view it.

When enhancing functionality with JavaScript, be careful not to block the functionality unnecessarily for non-JavaScript browsers. Always provide a fallback for any content. For example, to link to another web page but control that link with JavaScript, use:

<a href="blurbs/spanish.html" onClick="return view(this.href)">Some text</a>

By doing this, those without JavaScript (such as people using alternative browsers where JavaScript doesn’t make sense) will still be able to view that page.

Never block normal functionality. Do not, for example, do either of these:

<a href="missing.html" onClick="return view('blurbs/spanish.html')">Some text</a> <a href="javascript:view('blurbs/spanish.html')">Some text</a>

There’s no need for it. The same applies to image links, media links, and any other enhancements. Let people go to the link (or view the image or other media file) whether their browser supports JavaScript or not.

Also, never rely on JavaScript for security. You can use JavaScript to warn the viewer that their form submission is invalid, for example, but never trust that the JavaScript successfully blocked the invalid submission. Always implement security on the server side.

Appropriate use of Flash

Flash is never used for primary content. It can be used (like movies) for secondary content, but remember that Flash content is heavily dependent not just on the existence of Flash in the visitor’s browser but on the version. Where HTML content can be viewed by any browser since the beginning of the web, Flash content is locked to at least the version you’ve designed for.

Flash content is generally less useful (if not completely useless) for visitors using alternative browsers.

In general, if the content can be displayed using HTML and CSS, it should be. If the content is a movie or image, it should be displayed as a movie or image. Flash is useful only when you have a specific audience with specific technical resources in mind and are not worried about locking out visitors not in that audience. You should be able to articulate that audience without reference to the technology they use.

Sample indentation

Each section should be indented one more than the previous section. Elements that are at the same level structurally should be at the same indentation. For example:

<html> <head> <title>San Diego Weather</title> <meta name="keywords" value="San Diego, weather, sun" /> </head> <body> <h1>Weather Notes for San Diego</h1> <p>The weather for today is Sunny, 72.</p> <h2>More forecasts</h2> <p>San Diego weather varies greatly between beaches and mountains.</p> <ul> <li><a href="beaches/">Beach Forecast</a></li> <li><a href="inland/">Inland Forecast</a></li> <li><a href="mountain/">Mountain Forecast</a></li> </ul> </body> </html>

What we're looking at here is the actual HTML structure. What is the purpose of each element? Which elements contain which other elements? Which elements are co-equal with which other elements?

In other words, if we add a style to this “section”, which elements will that style apply to?

HTML version

Try to use strict XHTML 1.0, and validate against The W3C Markup Validation Service. Your DOCTYPE will be:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> … </html>

Depending on circumstances, you may also need to specify a charset. Use utf-8, and specify it in the HEAD of the document with:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

You can use transitional XHTML 1.0 or HTML 4 if you are editing a page that already exists (and if you do, make sure that the DOCTYPE is appropriately set), but for new designs always use strict XHTML 1.0.

Whatever version of HTML you use, be sure to validate it.

Character set and entities

Even though we’re using UTF-8 for our pages, continue to use entity names to put diacriticals, smart quotes, or other special characters in our pages. For example, use &aacute;, not á for an accented ‘a’. Don’t use the numerical entities; use their names.

This helps when editing pages in other editors on other platforms, and when managing content dynamically. It also ensures that such items will appear correctly if we have to use a different character set on any particular page.