Coding Style Guide for (X)HTML,CSS,JavaScript

Kai Hofmann <hofmann@hofmann-int.de>
21.08.2003

Table of Content

 1. Style guide background
 2. File/path/anchor/element naming conventions
 3. HTML versions
 4. Formatting code
 5. Using meta tags
 6. How to use CSS with HTML
 7. How to use JavaScript inside HTML
 8. How to use Flash inside HTML
 9. Graphic formats
10. Frames, layers and tables
11. References


1. Style guide background

This style guide describes how you should name and design HTML code.
The base idea behind all this is to improve the usability, performance, maintainance
and understandability of your HTML pages and web-application.
This guide tries to be browser independent. So using it should make your scheme more
portable to different web-browsers.


2. File/path/anchor/element naming conventions

Directory and file names should always be written in lower case because windows systems
are case insensitive and Unix systems are case sensitive. Also you should not use
language specific characters like the german öäüß in directory or file names, because
these might not work every where. Also spaces in file, directory and anchor names
are not allowed. Use the underline "_" character instead.
Try to sort your HTML documents in categories like "products, support, contact, ..."
and create a directory for each of these categories - naming the directory like the
category. Create sub directories when possible - for example for each product under
the "products" directory you should create an own directory which is named by the
products name.
Use simple and short names. For example use "datasheet.html" for all products datasheet
pages. "faq.html" would be a good name for freequently asked question files.
When you have a large list of faq's use parts added to the filename via an underscore "_".
For example "faq_installation.html". Using additions like "part1" etc. are a bad choice.
In each directory use "index.html, index.shtml or index.php" as the first page which
links to other pages in this directory.
Create the following sub-directories for extra content:

css   : Cascading style sheets
flash : Macromedia Flash files
js    : JavaScript code
pdfs  : PDF documents
pics  : Graphics files (gif, jpeg, png)
ssi   : Server side includes
w3c   : w3c specific meta data files

Put things that are used all over your web site in these directories that are found under the
root "/" directory. Graphics etc. that are specific to one product should be placed in the
pics folder under the products own directory.

When working with different languages you should name you documents as follows:

index.html.en : english version
index.html.de : german version
index.html.fr : french version

This will allow apache web servers to deliver the correct language via
content negotiation.

HTML anchors should be named in the same way as the additional parts to filenames.
So use <a name="html_versions"> instead of "chapter3".

HTML elements should be named via the old style "name" attribute and the new "id" attribute!
Use the same conventions as when naming anchors or additional filename parts.
All visible input elements of a form should be labeled by using the "label" tag.


3. HTML versions

Backward compatibility with older browsers can be reached by using XHTML 1.0 Transitional
as HTML version. So there is no requirement to use older HTML versions!
You should always start your HTML documents with:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">

XHTML 1.0 Transitional is very similar to HTML 4.0 except the following points:

- All tags and attribute names are written in lower case and have to be an end-tag
- Tags without an end tag are written as follows: <br />
  The space before the "/" is there for backward compatibility with older browsers!
- Every attribute value has to be placed in quotes like  <html lang="en">
- Attributes to switch on something like "selected" are written in the same style
  >option selected="selected"<


4. Formatting code

Place one Tag on one line and use two spaces for indention (this is the good old pascal style).
So your code should look like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html lang="de" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; CHARSET=ISO-8859-1" />
    <title>example</title>
  </head>

  <body>
    <h1>first example</h1>
    <p>abstract here</p>
    <form>
      <table>

        <tr>
          <td>text field</td>
          <td><input type="text" name="test" value="" /></td>
        </tr>
        <tr>

          <td>choose an option</td>
          <td>
            <select>
              <option>abc</option>
              <option>def</option>

            </select>
          </td>
        </tr>
      </table>
    </form>
  </body>

</html>

As you can see there is an exception from the one tag per line statement for the input field within the td tag.
This makes the code a little more compact.
Spaces at the end of line should be avoided. jedit [8] offers a whitespace plugin that will do this
during saving.
For the case that you want to compact the HTML that you put on a webserver try using HTMLCRunch [9]
bute be sure to keep the original code in a safe place!


5. Using meta tags

Meta tags should be used to add meta information to each page/site. These
information are useful for search engines, general spiders and also for some
browsers.
Meta tags can be divided into two categories. First the meta tags that might be
the same on all pages (of one language) for a site and secondly the tags that
are individual for each page:

Site/language specific meta tags

<meta http-equiv="Content-Type" content="text/html; CHARSET=ISO-8859-1" />
<meta http-equiv="Window-target" content="_top" />
<meta name="Content-Language" content="en" />

<meta name="author" lang="de" content="Dipl.-Inform. Kai Hofmann" />
<meta http-equiv="Reply-to" content="webmaster@hofmann-int.de" />
<meta name="creator" lang="de" content="Dipl.-Inform. Kai Hofmann" />

<meta name="publisher" content="Dipl.-Inform. Kai Hofmann" />
<meta name="copyright" content="© 1998-2003 Dipl.-Inform. Kai Hofmann" />
<meta name="distribution" content="global" />

<meta name="DC.Creator" content="Dipl.-Inform. Kai Hofmann" />
<meta name="DC.Publisher" content="Dipl.-Inform. Kai Hofmann" />
<meta name="DC.Language" content="en" />

<link rev="Made" href="mailto:webmaster@hofmann-int.de?subject=Mail to creator" title="EMail to webmaster" />
<link rev="Owns" href="mailto:webmaster@hofmann-int.de?subject=Mail to owner" title="EMail to webmaster" />

<link rel="home" href="/index.shtml.en" title="Dipl.-Inform. Kai Hofmann" />

Page specific meta tags

<title>Willkommen bei Dipl.-Inform. Kai Hofmann</title>

<meta name="revisit-after" content="3 months" />
<meta name="date" content="2002-12-06T21:00:00+01:00" />
<meta name="description" content="Dipl.-Inform. Kai Hofmann - Die Nummer 1 unter den Spezialisten für Kalenderberechnungen" />
<meta name="keywords" content="1582, 2000, Algorithmus, Computer, DateLib, Datum, Deutsche, Deutschland, Engineering, Entwicklung, Firma, Gregorianisch, Hilfe, Hofmann, International, Internet, ISO 8601, Jahr, Jahrhundert, Jahrtausend, Julianisch, Kalender, Kalenderreform, Lösung, Online, Papst Gregor XIII, Reform, Schaltjahr, Software, Sommerzeit, Willkommen, www, Zeit, Zukunft" />

<meta name="type" content="Produktinfo, Firmen Homepage, Software Download, Katalog Verzeichnis, Bericht Reportage, Anleitung" />
<meta name="page-topic" content="Bildung, Branche Produkt, Dienstleistung, Forschung Technik, Wirtschaft, Wissenschaft, Religion, Verwaltung, Medien, Medizin" />
<meta name="page-type" content="Produktinfo, Firmen Homepage, Software Download, Katalog Verzeichnis, Bericht Reportage, Anleitung" />
<meta name="audience" content="Alle, Anfänger, Azubis, Erwachsene, Experten, Fortgeschrittene, Frauen, Jugendliche, Männer, Profis, Schüler, Studenten" />
<meta name="ROBOTS" content="INDEX, FOLLOW" />

<link href="index.shtml.en" rel="alternate" type="text/html" hreflang="en" title="Diese Seite in Englisch" />

<meta http-equiv="pics-label" content='(pics-1.1 "http://www.icra.org/ratingsv02.html" comment "Basic form v 2.0" l gen true for "http://www.isl.org/" r (nz 1 vz 1 lz 1 oz 1 cz 1) "http://www.rsac.org/ratingsv01.html" l gen true for "http://www.isl.org/" r (n 0 s 0 v 0 l 0))' />
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.classify.org/safesurf/" l gen true for "http://www.isl.org/" r

Please note that there are a lot of other meta tag names available for example at [11]. For pics rating systems take a look (for example) at [12] and [13].


6. How to use CSS with HTML

Cascading Style Sheets should only be used via external style sheet files and using
the class attribute of html elements. External style sheets will be easier to
maintain and customize. Also its possible to have different style sheets for
different media types like printing and projection.
External style sheets will be included by using the link html tag element:


<link rel="stylesheet" href="/css/style-screen.css" type="text/css" media="screen" />
<link rel="stylesheet" href="/css/style-print.css" type="text/css" media="print" />
<link rel="stylesheet" href="/css/style-projecion.css" type="text/css" media="projection" />
<link rel="stylesheet" href="/css/style-screen.css" type="text/css" media="all" />

A CSS file by itself should be formated in the following way:

body
 {
  background-color:#ffffff;
  color:#000063;
  font-family:Arial, Helvetica, sans-serif;
  font-size:10pt;

 }

h1
 {
  font-weight:bold;
  font-size:16pt;
  /* Netscape inherit bug */
  font-family:Arial, Helvetica, sans-serif;
  color:#000063;
 }

Please verify each CSS file by the w3c css-validator [2].

To inform users that CSS has been switched off please use the following code fragments:

h1.invisible
 {
  display:none;
 }

p.invisible
 {
  display:none;
 }

<h1 class="invisible">Please activate Cascading Style Sheets (and in Netscape 4 also JavaScript)!</h1>
<p class="invisible">If you could read this text then CSS has been disabled or in Netscape 4 maybe JavaScript!</p>


7. How to use JavaScript inside HTML

Use JavaScript only in a defensive way so that the webpage is still
usable without JavaScript.
JavaScript should be used via external script files that will be included in
the following way:

<script language="JavaScript1.1" type="text/javascript" src="js/index.js"></script>

Within such an external JavaScript file JavaScript should be used in an object oriented
style that is compatible to the W3C DOM specification [14] - by defining classes with methods
that will be used within the HTML file.
These classes and methods should be documented by using jsdoc.
Within a HTML file the above file inclusion should happen within the head element section.
After this one a script section that creates the required object should appear.
Only short javascript statements (method calls) are allowed within the event handler
attributes of html elements.
Move any JavaScript code that takes more than one line into a class or a function
in an external script file.
Test all JavaScript via Mozilla and the JavaScript Console so that there are no syntax errors.
For more about JavaScript coding style refer to the coding style guide [15].


8. How to use Flash inside HTML

Flash should be used in a way that the webpage is still usable without a flash plugin.
For using flash in a XHTML 1.0 Transitional compatible way that also works with all available
browsers please use the following code:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" codebase=" http://active.macromedia.com/flash5/cabs/swflash.cab#version=5,0,0,0" width="400" height="400">
  <param name="movie" value="flash/intro.swf" />
  <param name="play" value="true" />
  <param name="loop" value="false" />

  <param name="menu" value="false" />
  <param name="wmode" value="opaque" />
  <param name="bgcolor" value="#ffffff" />
  <script type="text/javascript"><!--
    if (navigator.plugins && (navigator.plugins.length > 0) && navigator.plugins["Shockwave Flash"])
     {
      document.write("<embed src=\"flash/intro.swf\" width=\"400\" height=\"400\" play=\"true\" loop=\"false\" pluginspace=\"http://www.macromedia.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash\" swliveconnect=\"false\" menu=\"false\"></embed>");
     }
    else
     {
      document.write("<img src=\"pics/intro.jpeg\" width=\"400\" height=\"400\" alt=\"Intro Logo\" />");
     }
    // -->

  </script>
  <noscript>
    <img src="pics/intro.jpeg" width="400" height="400" alt="Intro Logo" />
  </noscript>
</object>

This code has a fallback so that an image will be dislayed when no flash plugin is available.


9. Graphic formats

For including graphics especially in the navigation bar or the heading area please try to use
standard banner formats. This will allow you to use a lot of already existing graphics as
well as placing advertising banners there when the need would be there.

Standard formats are:

Most popular   : 468*60, 88*31, 120*90, 102*47
Often mentioned: 120*600, 160*600
Mentioned      : 468*120, 250*250, 200*300, 234*60, 156*60,
                 125*125, 400*50, 180*150, 120*60, 150*150,
                 148*800, 148*400, 234*68, 120*240, 125*125


10. Frames, layers and tables

Frames should not be used, because they bring trouble into navigation,
search-engine-spiders have problems with them - also linking from
an external resource to a content page might beak the whole site

(missing navigation) and last but not least frames are a problem for
people with disablilities.
Everything that can be done with a frame is also possible by using
tables and/or div elements.

Layers should also be used in a defensive way so that the webpage
still works witout them. For example when using layers for tabs
they could be implemented with a fallback so that when css/javascript
ist not available that all tabs will be displayed below each other.


11. References

[1] W3C MarkUp Validation Service
    http://validator.w3.org/

[2] CSS Validator
    http://jigsaw.w3.org/css-validator/

[3] Checklink
    http://validator.w3.org/checklink

[4] Bobby
    http://bobby.watchfire.com/bobby/html/en/index.jsp

[5] Mozilla
    http://www.mozilla.org/

[6] Checky
    http://checky.mozdev.org/

[7] WebReview.com's Style Sheet Reference Guide
    http://www.ddj.com/webreview/style/

[8] jedit
    http://www.jedit.org/

[9] HTMLCRunch
    http://www.markusstengel.de/htmlcr.html

[10] Style Guide for online hypertext
     http://www.w3.org/Provider/Style/

[11] Dublin Core Metadata Initiative
     http://www.dublincore.org/

[12] Internet Content Rating Assiciation
     http://www.icra.org/

[13] The Information Classification Group
     http://www.classify.org/

[14] Document Object Model (DOM)
     http://www.w3.org/DOM/

[15] Coding Style Guide for C,C++,Java,PHP,JavaScript (Kai Hofmann)
     not available yet