Style guide

HTML is well specified with regards to syntax but there is still a significant amount of room to produce horrific looking code. We should always aim to write good HTML code. What constitutes good HTML code is subjective but coding practices have developed and the community of web developers have come to a consensus. The following section covers the HTML coding style that has developed.

HTML elements

Although not all HTML elements have to be closed, that is you can omit the closing tag from some elements without making the web page display incorrectly, it is bad form and makes for difficult to read HTML code. If the HTML element is empty then use the self closing HTML element.

All HTML should be in lower case letters. Do not capitalise or upper-case HTML element names.

All HTML attribute names should be in lower case letters. Do not capitalise or upper-case HTML attribute names.

Always enclose attribute values in quotes.

Do not omit html, body or head elements. Although they are strictly not required they add structure to a HTML document which makes it easier to read when making alterations.

Use the correct DOCTYPE.

Blank lines and indentation

HTML allows for spaces, indentation and blank lines anywhere in the document and it will have minimal effect on the display of the web page. You should not introduce additional unnecessary white space. Where the introduction of white space improves readability then this is acceptable. Such instances include long lines (lines over 120 character). To improve readability two new lines should be added between large blocks of HTML or logical code blocks. Use two spaces instead of tabs. When setting HTML attribute values do not introduce spaces in between the attribute name and the equals sign, and the equals sign and the attribute value.

Bad

<img src="cute_kittens.gif" alt = "kittens" style = "width:128px;height:128px">

Good

<img src="cute_kittens.gif" alt="kittens" style="width:128px;height:128px">

HTML Comments

Use HTML comments. Comments are a very useful feature of any programming language (or markup language). Comments are useful when trying to understand why the previous person who worked on the document made the design choices they did. They are also useful to provide separation of content in HTML documents. When there is a long container element it is easy to 'loose' the corresponding closing elements. Comments can help but putting a comments on closing elements. Always leave a space before and after a comment.

<!-- Like this -->

Style sheets

External style sheets should be used wherever possible. CSS is a powerful tool and it should be used accordingly. When laying out CSS the following format should be adhered to.

  • Place the opening bracket on the same line as the selector.
  • Use one space before the opening bracket.
  • Use 2 spaces of indentation.
  • Use colon plus one space between each property and its value.
  • Use space after each comma or semicolon.
  • Use semicolon after each property-value pair, including the last.
  • Only use quotes around values if the value contains spaces.
  • Place the closing bracket on a new line, without leading spaces.
  • Avoid lines over 80 characters.

File extensions

Always use lower case filenames when naming web resources, this convention arises from differences in windows and unix systems. HTML documents should have the file extension .html. JavaScript files should have the file extension .js. CSS files should have the file extension .css.