Code Guide

Golden rule
HTML
CSS
Writing copy
- Sentence case

Golden rule

All code in any code base should look like a single person typed it, no matter how many people contributed.

This means strictly enforcing these agreed upon guidelines at all times. For additions or contributions, please file an issue on GitHub.

HTML

HTML syntax

Use soft-tabs with two spaces
Nested elements should be indented once (2 spaces)
Always use double quotes, never single quotes
Don't include a trailing slash in self-closing elements

Incorrect example:

<!DOCTYPE html>
<html>
<head>
<title>Page title</title>
</head>
<body>
<img src='images/company-logo.png' alt='Company' />
<h1 class='hello-world'>Hello, world!</h1>
</body>
</html>

Correct example:

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.

<!DOCTYPE html>

Pragmatism over semantics

Strive to maintain HTML standards and semantics, but don't sacrifice pragmatism. Use the least amount of markup with the fewest intricies whenever possible.

Attribute order

HTML attributes should come in this particular order for easier reading of code.

class
id
data-*
for|type|href

Such that your markup looks like:

<a class="" id="" data-modal="" href="">Example link</a>

JavaScript generated markup

Writing markup in a javascript file makes the content harder to find, harder to edit, and less performant. Don't do it.

CSS

CSS syntax

Use soft-tabs with two spaces
When grouping selectors, keep individual selectors to a single line
Include one space before the opening brace of declaration blocks
Place closing braces of declaration blocks on a new line
Include one space after : in each property
Each declaration should appear on its own line
End all declarations with a semi-colon
Comma-separated values should include a space after each comma
Don't include spaces after commas in RGB or RGBa colors, and don't preface values with a leading zero
Lowercase all hex values, e.g., #fff instead of #FFF
Use shorthand hex values where available, e.g., #fff instead of #ffffff
Quote attribute values in selectors, e.g., input[type="text"]
Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;

Incorrect example:

.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

Correct example:

.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin: 0 0 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Questions on the terms used here? See the syntax section of the Cascading Style Sheets article on Wikipedia.

Declaration order

Related declarations should be grouped together, placing positioning and box-model properties closest to the top, followed by typographic and visual properties.

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

For a complete list of properties and their order, please see Recess.

Formatting exceptions

In some cases, it makes sense to deviate slightly from the default syntax.

Prefixed properties

When using vendor prefixed properties, indent each property such that the value lines up vertically for easy multi-line editing.

.selector {
  -webkit-border-radius: 3px;
     -moz-border-radius: 3px;
          border-radius: 3px;
}

In Textmate, use Text → Edit Each Line in Selection (⌃⌘A). In Sublime Text 2, use Selection → Add Previous Line (⌃⇧↑) and Selection → Add Next Line (⌃⇧↓).

Rules with single declarations

In instances where several rules are present with only one declaration each, consider removing new line breaks for readability and faster editing.

.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Human readable

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.

Comments

Great code comments convey context or purpose and should not just reiterate a component or class name.

Bad example:

/* Modal header */
.modal-header {
  ...
}

Good example:

/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Class names

Keep classes lowercase and use dashes (not underscores or camelCase)
Avoid arbitrary shorthand notation
Keep classes as short and succinct as possible
Use meaningful names; use structural or purposeful names over presentational
Prefix classes based on the closest parent component's base class

Bad example:

.t { ... }
.red { ... }
.header { ... }

Good example:

.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectors

Use classes over generic element tags
Keep them short and limit the number of elements in each selector to three
Scope classes to the closest parent when necessary (e.g., when not using prefixed classes)

Bad example:

span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

Good example:

.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organization

Organize sections of code by component
Develop a consistent commenting hierarchy
If using multiple CSS files, break them down by component

Copy

Sentence case

Always write copy, including headings and code comments, in sentence case. In other words, aside from titles and proper nouns, only the first word should be capitalized.

Thanks

Heavily inspired by Idiomatic CSS and the GitHub Styleguide. Made with all the love in the world by @mdo.

Table of contents

Golden rule

HTML

HTML syntax

HTML5 doctype

Pragmatism over semantics

Attribute order

JavaScript generated markup

CSS

CSS syntax

Declaration order

Formatting exceptions

Prefixed properties

Rules with single declarations

Human readable

Comments

Class names

Selectors

Organization

Copy

Sentence case

Thanks