HTML Code Conventions ~ Web CodeHelpers

HTML Code Conventions

HTML Code Conventions


The purpose of this document is to provide guidelines for writing HTML at PayPal. Code conventions are important for the long-term maintainability of code. Most of the time, developers are maintaining code, either their own or someone else’s. Code conventions provide a common dialect with which developers communicate through code with one another.

HTML Style Guide

Style guides provide basic syntax and formatting guidance. The goal is to have everyone’s code look the same, which allows any developer to easily work on another developer’s code.

Indentation

Each indentation level is made up of one tab character. Do not use spaces.
?
1
2
3
4
5
6
<!-- Good -->
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ul>

Elements

All tag names on all elements must be all lowercase.
?
1
2
3
4
5
<!-- Good -->
<p>Hello world!</p>
<!-- Bad: uppercase tags -->
<P>Hello world!</P>
Elements for which a closing tag is forbidden in HTML must use XHTML self-closing style with an extra space before the slash.
?
1
2
3
4
5
6
7
8
<!-- Good -->
<input type="text" />
<!-- Bad: Not self-closing -->
<input type="text">
<!-- Bad: Missing space before slash -->
<input type="text"/>
Elements for which the closing tag is optional must always include the closing tag.
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- Good -->
<p>Hello world!</p>
<ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
</ul>
<!-- Bad: Missing closing tags -->
<p>Hello world!
<ul>
    <li>Item 1
    <li>Item 2
    <li>Item 3
</ul>

Attributes

Attribute names must be in all lowercase.
?
1
2
3
4
5
6
7
8
<!-- Good -->
<div class="dialog">
<!-- Bad: Mixed case attribute name -->
<div Class="dialog">
<!-- Bad: Uppercase attribute name -->
<div CLASS="dialog">
There should be no space between the attribute name and attribute value.
?
1
2
3
4
5
<!-- Good -->
<div class="dialog">
<!-- Bad: Spaces around equals sign -->
<div class "dialog">
Attribute values must always be quoted using double quotes.
?
1
2
3
4
5
6
7
8
<!-- Good -->
<div class="dialog">
<!-- Bad: Missing quotes -->
<div class=dialog>
<!-- Bad: Using single quotes -->
<div class='dialog'>
Boolean attributes, those attributes that don’t require a value in HTML, must always include an attribute value.
?
1
2
3
4
5
<!-- Good -->
<input type="text" required="required" />
<!-- Bad: Missing value-->
<input type="text" required />

Document Structure

Every HTML document must follow this basic structure:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Page title</title>
    <meta charset="UTF-8" />
    <!-- other meta tags -->
    <!-- stylesheet and other link references -->
    <!-- JavaScript references -->
</head>
<body>
    <!-- content -->
</body>
</html>
The key parts of this document structure are:
. This is where the page content goes.
  1. Every HTML document must begin with the HTML5 doctype.
  2. Immediately following the doctype must be the <html>element. The lang attribute must be set to the appropriate language for the page.
  3. The next element should be <head>, which should contain <title>and <meta charset="UTF-8">as the first two children. After that may come, in order, additional meta information, stylesheet and other <link>references, and JavaScript references.
  4. After <head>should be
  5. All of these elements must be present and closed appropriately.
If the document's main language is a right-to-left language, include the dirattribute on the <html>element:
?
1
2
<!-- Good -->
<html lang="en" dir="rtl">
Do not use the CSS directionproperty for this purpose.

JavaScript

JavaScript should be included using the <script>element. The typeattribute should not be included.
?
1
2
3
4
5
<!-- Good -->
<script src="paypay.js"></script>
<!-- Bad: Using type -->
<script type="text/javascript" src="paypay.js"></script>
Whenever possible, JavaScript should be contained in separate files rather than being included inline in HTML. If necessary, inline scripts may be used provided that they are as small as possible. Inline scripts should not use HTML comments.
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!-- Good -->
<script>
var PAYPAL_ID = "asd098qawlkjasdf";
</script>
<!-- Bad: Using type -->
<script type="text/javascript">
var PAYPAL_ID = "asd098qawlkjasdf";
</script>
<!-- Bad: Using HTML comments -->
<script>
<!--
var PAYPAL_ID = "asd098qawlkjasdf";
//-->
</script>
JavaScript event handlers should be attached only using JavaScript and never in HTML.
?
1
2
<!-- Bad: Uses inline event handler -->
<button onclick="doSomething()">Click Me</button>

Style Sheets

CSS style sheets should be included using the <link>element. The typeattribute should not be included and the mediaattribute isn't required unless the style sheet shouldn't be used by default (for example, if it only applies to print).
?
1
2
3
4
5
<!-- Good -->
<link rel="stylesheet" href="paypal.css" />
<!-- Bad: Using type -->
<link rel="stylesheet" type="text/css" href="paypay.css" />

Tags to Avoid

Certain tags should not be used. All officially deprecated or obsoleted tags should not be used (see HTML5 Obsolete Elements).
In addition, the following tags should not be used:
  • <address>
  • <br>
  • <noscript>

Programming Practices

Programming practices are another type of code convention. Where style guidelines are concerned with the appearance of code, programming practices are concerned with the outcome of the code. You can think of programming practices like recipes - they help developers write their code in such a way that the end result is already known. If you've ever used design patterns such as the observer pattern of the model-view-controller (MVC), then you're already familiar with programming practices. Design patterns are programming practices that solve specific problems related to software organization.

Headings

All pages must have just one <h1>element. Do not use <h1>inside of <section>elements.
?
1
2
3
4
5
6
7
8
9
10
11
12
<!-- Good -->
<body>
    <h1>Page Title</h1>
</body>
<!-- Bad: Multiple h1s -->
<body>
    <h1>Page Title</h1>
    <section>
        <h1>Section Title</h1>
    </section>
</body>
For links that initiate JavaScript behavior, the hrefmust contain either a valid URL for alternate content or an ID reference in the form#id, such as #close. In this case, the JavaScript attaching the event handler must also add a roleattribute equal to buttonto indicate to screen readers that the link is non-navigational.
?
1
2
3
4
5
6
7
8
<!-- Good -->
<a href="#close">Close</a>
<!-- Bad: role should be added only by JavaScript -->
<a href="#close" role="button">Close</a>
<!-- Bad: href isn't a valid ID -->
<a href="#">Close</a>

The title Attribute

The titleattribute should be used sparingly, and only in cases where it's providing additional information that isn't apparent from the markup. For instance, there is no reason to provide a titleattribute that duplicates a link's text or an image's altattribute. Thettitleattribute is required when using the patternattribute on an <input>element.
?
1
2
3
4
5
6
7
8
<!-- Good -->
<input type="text" pattern="[\d]+" title="Numbers only" />
<!-- Bad: Duplicating link content -->
<a href="http://www.paypal.com" title="PayPal">PayPal</a>
<!-- Bad: Duplicating alt content -->
<img src="logo.png" alt="PayPal" title="PayPal" />

Tables

Tables may only be used to structure tabular data–information organized in rows and columns, similar to a spreadsheet. In all other cases, CSS must be used.
Tables must contain a <caption> element that contains the title of the table. If this content should not be displayed on the page, use theaccessAid CSS class on the <caption> element. Each <th> element may have a scope attribute indicating whether it applies to a row or a column. Scope is optional but recommended.
For complex tables (more than 1 level of row or column headers), the scope or headers attributes must be used to make the content accessible. The summary attribute is no longer recommended.
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!-- Good -->
<table>
    <caption>PayPal Balance</caption>
    <tr>
        <th scope="col">Currency</th>
        <th scope="col">Balance</th>
    </tr>
    <tr>
        <td>U.S. Dollar</td>
        <td>$1.00 USD</td>
    </tr>
</table>
<!-- Bad: missing caption, TH, scope -->
<table>
    <tr>
        <td>Currency</td>
        <td>Balance</td>
    </tr>
    <tr>
        <td>U.S. Dollar</td>
        <td>$1.00 USD</td>
    </tr>
</table>

Form Input Fields

All form input fields must be accompanied by a <label>element describing their use regardless of UI design. If necessary, you may hide the <label>using the accessAidclass. Do not put the input element inside of <label>.
?
1
2
3
4
5
6
7
8
9
10
<!-- Good -->
<label for="userEmail">E-mail:</label> <input type="email"
name="userEmail" id="userEmail" />
<!-- Good -->
<label for="userEmail" class="accessAid">E-mail:</label> <input
type="email" name="userEmail" id="userEmail" />
<!-- Bad -->
<label>E-mail:<input type="email" name="userEmail" id="userEmail" /></label>

Form Input Types

The following <input>types may be used:
  • button
  • checkbox
  • email
  • file
  • hidden
  • number
  • radio
  • submit
  • tel
  • text
  • url
Avoid using the following <input>types:
  • color
  • date
  • range
  • reset

Form Radio Buttons

When radio buttons are used on a form, use a <fieldset>element to enclose the options and use the <legend>element to specify the text that corresponds to all radio buttons. Use an unordered list where each item is one radio button, and each radio button has its own<label>.
?
1
2
3
4
5
6
7
8
9
<!-- Good -->
<fieldset>
    <legend>Payment for:</legend>
    <ul>
        <li><input type="radio" id="payment_type_service" value="S"> <label for="payment_type_service">Service/Other</label></li>
        <li><input type="radio" id="payment_type_goods" value="G"> <label for="payment_type_goods">Goods</label></li>
        <li><input type="radio" id="payment_type_cash" value="C"> <label for="payment_type_cash">Cash Advance</label></li>
    </ul>
</fieldset>

HTML5 Block Elements

Use HTML5 structural elements (<section><article><header><footer> and <nav>) for the main page grid.
?
1
2
3
4
5
6
<!-- Good -->
<section><div>
    <h2