HTML(5) Style Guide and Coding Conventions

HTML coding conventions

Web developers often do not know which coding style and syntax to use in HTML.

Between 2000 and 2010, many web developers switched from HTML to XHTML.

Through XHTML, developers had to write valid 'well-formed' code.

HTML5 is more lenient in code validation.

Through HTML5, you must create your ownBest practices, style guides, and coding conventions.

Intelligent and future-proof

Logical use of styles can make it easier for others to understand and use your HTML.

In the future, programs like XML readers may need to read your HTML.

Using well-formed 'approximate XHTML' syntax can be more intelligent.

Comment:Please keep your styles smart, tidy, clean, and well-formatted.

Please use the correct document type

Always declare the document type at the beginning of the document:

<!DOCTYPE html>

If you consistently use lowercase tags, then you can use:

<!doctype html>

Please use lowercase element names

HTML5 allows mixed case letters to be used in element names.

We recommend using lowercase element names:

  • Mixed case names are not good
  • Developers are accustomed to using lowercase names (such as in XHTML)
  • Lowercase looks cleaner
  • Lowercase is easier to write

Not so good:

<SECTION> 
  <p>This is a paragraph.</p>
</SECTION>

Terrible:

<Section> 
  <p>This is a paragraph.</p>
</SECTION>

Not bad:

<section> 
  <p>This is a paragraph.</p>
</section>

Close all HTML elements

In HTML5, you do not have to close all elements (such as <p> elements).

We recommend closing all HTML elements:

It looks bad:

<section>
  <p>This is a paragraph.
  <p>This is a paragraph.
</section>

It looks good:

<section>
  <p>This is a paragraph.</p>
  <p>This is a paragraph.</p>
</section>

Closing empty HTML elements

In HTML5, it is optional to close empty elements.

It is allowed to be like this:

<meta charset="utf-8">

It is also allowed to be like this:

<meta charset="utf-8" />

The slash (/) is required in XHTML and XML.

If you expect XML software to access your page, it is a good idea to maintain this habit.

Use lowercase attribute names

HTML5 allows mixed-case attribute names.

We recommend using lowercase attribute names:

  • Mixed attribute names are not good
  • Developers are accustomed to using lowercase attribute names (such as in XHTML)
  • Lowercase attribute names are cleaner when used appropriately
  • Lowercase attribute names are easier to write

It looks bad:

<div CLASS="menu">

It looks good:

<div class="menu">

Quoted attribute values

HTML5 allows attribute values without quotes.

We recommend that attribute values be quoted:

  • If the attribute value contains a value, it must be quoted
  • Mixed styles are absolutely bad
  • Quoted values are easier to read

This attribute value is invalid because it contains spaces:

<table class=table striped>

This is valid:

<table class="table striped">

Required attribute

Always use alt Attribute. This attribute is important when the image cannot be displayed.

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

Always define the image size. This will reduce flickering because the browser will reserve space for the image before it loads.

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

Spaces and equal sign

Spaces on both sides of the equal sign are legal:

<link rel = "stylesheet" href = "styles.css">

But concise spacing is easier to read, But space-less is easier to read, and groups entities better together:

<link rel="stylesheet" href="styles.css">

Avoid long code lines

It is very inconvenient to read HTML code by scrolling left and right when using an HTML editor.

Try to avoid code lines exceeding 80 characters.

Blank lines and indentation

Do not add blank lines without reason.

Increase blank lines to separate large or logical code blocks.

Increase two spaces of indentation to improve readability. Do not use TAB.

Do not use unnecessary blank lines and indentation.

Not necessary:

<body>
  <h1>Famous Cities</h1>
  <h2>Tokyo</h2>
  <p>
    Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
    and the most populous metropolitan area in the world.
    It is the seat of the Japanese government and the Imperial Palace,
    and the home of the Japanese Imperial Family.
  </p>
</body>

Better:

<body>
<h1>Famous Cities</h1>
<h2>Tokyo</h2>
<p>
Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
and the most populous metropolitan area in the world.
It is the seat of the Japanese government and the Imperial Palace,
and the home of the Japanese Imperial Family.
</p>
</body>

Table example:

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
  <tr>
  <tr>
    <td>A</td>
    <td>Description of A</td>
  <tr>
  <tr>
    <td>B</td>
    <td>Description of B</td>
  <tr>
</table>

List example:

<ol>
  <li>LondonA</li>
  <li>Paris</li>
  <li>Tokyo</li>
</ol>

Omitting <html> and <body>?

In the HTML5 standard, the <html> tag and <body> tag can be omitted.

The following code is validated as HTML5:

示例

<!DOCTYPE html>
<head>
  <title>Page Title</title>
</head>
<h1>This is a heading</h1>
<p>This is a paragraph.</p>

Try It Yourself

We do not recommend omitting the <html> and <body> tags.

The <html> element is the root element of the text. It is the ideal location to specify the page language.

<!DOCTYPE html>
<html lang="en-US">

For accessible applications (screen readers) and search engines, declaring the language is important.

Omitting <html> or <body> may cause DOM and XML software to crash.

Omitting <body> may cause errors in older browsers (IE9).

Omitting <head>?

In the HTML5 standard, the <head> tag can also be omitted.

By default, the browser adds all elements before <body> to the default <head> element.

By omitting the <head> tag, you can reduce the complexity of HTML:

示例

<!DOCTYPE html>
<html>
<title>Page Title</title>
<body>
  <h1>This is a heading</h1>
  <p>This is a paragraph.</p>
</body>
</html>

Try It Yourself

Comment:For web developers, omitting tags is a foreign practice. Establishing rules takes time.

Metadata

The <title> element is required in HTML5. Please create meaningful titles as much as possible.

<title>HTML5 Syntax and Coding Style</title>

The sooner the definition of language and character encoding is made in the document, the better to ensure proper interpretation and correct search engine indexing:

<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title>HTML5 Syntax and Coding Style</title>
</head>

HTML Comments

Short comments should be written on a single line, with a space after <!-- and before -->:

!-- This is a comment --

Long comments that span multiple lines should be written on separate lines using <!-- and -->:

<!-- 
  This is a long comment example. This is a long comment example. This is a long comment example.
  This is a long comment example. This is a long comment example. This is a long comment example.
-->

Long comments are more visible if they are indented with two spaces.

Style Sheets

Please use simple syntax to link style sheets (the type attribute is not required):

<link rel="stylesheet" href="styles.css">

Short rules can be compressed into a single line, like this:

p.into {font-family:"Verdana"; font-size:16em;}

Long rules should be split into multiple lines:

body {
  background-color: lightgrey;
  font-family: "Arial Black", Helvetica, sans-serif;
  font-size: 16em;
  color: black;
}
  • The opening bracket is on the same line as the selector
  • Use a space before the opening bracket
  • Use two-character indentation
  • Use a colon followed by a space between each attribute and its value
  • Use spaces after each comma or semicolon
  • Use semicolons after each attribute-value pair (including the last one)
  • Use quotes to enclose values only when they contain spaces
  • Place the closing bracket on a new line, without spaces before it
  • Avoid lines that exceed 80 characters

Comment:Adding spaces after commas or semicolons is a universal rule for all types of writing.

Load JavaScript in HTML

Please use simple syntax to load external scripts (the type attribute is not required):

<script src="myscript.js">

Accessing HTML Elements via JavaScript

The consequence of using 'messy' HTML styles is that it may cause JavaScript errors.

These two JavaScript statements will produce different results:

var obj = getElementById("Demo")
var obj = getElementById("demo")

Try It Yourself

If possible, use the same naming conventions in HTML as (with) JavaScript.

Please visit the JavaScript Style Guide.

Use lowercase filenames

Most web servers (Apache, Unix) are case-sensitive for filenames:

You cannot access London.jpg with london.jpg.

Other web servers (Microsoft, IIS) are case-insensitive:

It is possible to access London.jpg with london.jpg or London.jpg.

If you use mixed case, you must maintain high consistency.

If you move from a case-insensitive server to a case-sensitive server, these small errors will break your website.

To avoid these problems, always use lowercase filenames (if possible).

File Extensions

HTML file names should use the extension .html(instead of .htm)

CSS files should use the extension .css.

JavaScript files should use the extension .js.