Skip to content

HTML

Jump to bottom
Carstairs edited this page May 28, 2019 · 7 revisions

This covers HTML written directly in HTML5, or in a related language that compiles to HTML - e.g. Pug, Angular or JSP.

HTML5

Use the HTML5 doctype for all new and, when possible, refactored code. Code should be as valid as IBM's application will allow within W3C's standards (validate with the W3C's validator).

<!DOCTYPE html>

Accessibility

Markup should be well-formed and include all the required attributes, and should pass an accessibility check at an "A" level. A tool such as SiteImprove can run the checks for you.

Semantic HTML

Semantic HTML is the use of HTML markup to reinforce the semantics, the meaning, of the information in webpages and web applications rather than merely to define its presentation or look.

If there is a tag that has the meaning of the content, that is what the tag around the content should be - not a div.

HTML5 introduced new structural tags which have browser support, as well as the HTML4 element tags which are already supported.

Page Element Tags

We should make regular use of these in our page structure:

  • header
  • footer
  • nav
  • main - this should wrap the main content section, highly useful for accessibility
  • section - wraps multiple divisions of a page

Ones we don't use as much: article, aside, figure, figcaption, time, mark

But Note! In cases where the HTML needs to be as backwards-compatible as possible, do not apply IDs or classes to them, since older browsers do not understand these elements by default and will not apply styling to them.

Head Information

Title

Each page should have a unique title describing it's content, and the information in the title tag should be ordered from most specific to least specific.

<title>Widget A1234 Product Details - Cooper Electric</title>

Meta Tags

As early as possible in your page, include the tag that tells IE/Edge what to do. This prevents it from rendering then re-rendering the page:

<meta http-equiv="X-UA-Compatible" content="ie=edge">

Set your site up for phones with the viewport tag:

<meta name="viewport" content="width=device-width, initial-scale=1">

And set the character encoding:

<meta charset="UTF-8">

HTML Comments

Comments in HTML are both informational and can provide signposts to find the section you want to work with quickly. Comments should note things that are useful to glean with a quick skim, or are not easily apparent from the HTML itself.

This should include (but isn't limited to):

  • Large page sections (signposting)
  • What partial views are in use and if they have variables or dependencies
  • Interactions
  • Dynamic content placeholders/locations

Comments For Backend Developers

Comments with things that other developers need to know – eg, things backend developers need to integrate – should be noted with @todo, @note, or @changes comments. This allows your partner dev to search and find what to work on quickly and easily, and understand what you've done and what they need to do.

Clone this wiki locally