The following document outlines a reasonable style guide for HTML development. These guidelines strongly encourage the use of existing, common, sensible patterns. They should be adapted as needed to create your own style guide.
This is a living document and new ideas are always welcome. Please contribute.
Only one style should exist across the entire source of your code-base. Always be consistent in your use of whitespace. Use whitespace to improve readability.
Tip: configure your editor to “show invisibles”. This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.
checked
rather than checked="checked"
).type
attributes from link
stylesheet, style
and script
elements.(Keep line-length to a sensible maximum, e.g., 80 columns.)
Example:
<div class="tweet">
<a href="path/to/somewhere">
<img src="path/to/image.png" alt="">
</a>
<p>[tweet text]</p>
<button disabled>Reply</button>
</div>
Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs.
Example:
<a class="[value]"
data-action="[value]"
data-id="[value]"
href="[url]">
<span>[text]</span>
</a>
HTML attributes should be listed in an order that reflects the fact that class names are the primary interface through which CSS and JavaScript select elements.
class
id
data-*
Example:
<a class="[value]" id="[value]" data-name="[value]" href="[url]">[text]</a>
Naming is hard, but very important. It’s a crucial part of the process of developing a maintainable code base, and ensuring that you have a relatively scalable interface between your HTML and CSS/JS.
Example with bad names:
<div class="cb s-scr"></div>
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
Example with better names:
<div class="column-body is-scrollable"></div>
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
An example of various conventions.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Document</title>
<link rel="stylesheet" href="main.css">
<script src="main.js"></script>
</head>
<body>
<article class="post" id="1234">
<time class="timestamp">March 15, 2012</time>
<a data-id="1234"
data-analytics-category="[value]"
data-analytics-action="[value]"
href="[url]">[text]</a>
<ul>
<li>
<a href="[url]">[text]</a>
<img src="[url]" alt="[text]">
</li>
<li>
<a href="[url]">[text]</a>
</li>
</ul>
<a class="link-complex" href="[url]">
<span class="link-complex__target">[text]</span>
[text]
</a>
<input value="text" readonly>
</article>
</body>
</html>