Skip to content

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

Kai Hofmann powerstat@web.de
21.08.2003

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.

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.

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">

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] but be sure to keep the original code in a safe place!

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].

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 it's 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>

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].

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

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 is not available that all tabs will be displayed below each other.

References

Bibliography

  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

TODO

  1. notepad++, https://notepad-plus-plus.org/

  2. Google Lighthouse, https://developers.google.com/web/tools/lighthouse/

  3. HTML5, https://html.spec.whatwg.org/multipage/