index.html

---
layout: default
---


<div class="heading" id="toc">
  <h2>Table of contents</h2>
</div>
<div class="section toc">
  <div class="col">
    <ul>
      <li><a href="#golden-rule">Golden rule</a></li>
      <li><a href="#html">HTML</a>
        <ul>
          <li><a href="#html-syntax">Syntax</a></li>
          <li><a href="#html-doctype">HTML5 doctype</a></li>
          <li><a href="#html-practicality-over-purity">Practicality over purity</a></li>
          <li><a href="#html-attribute-order">Attribute order</a></li>
          <li><a href="#html-boolean-attributes">Boolean attributes</a></li>
          <li><a href="#html-reducing-markup">Reducing markup</a></li>
          <li><a href="#html-javascript">JavaScript generated markup</a></li>
        </ul>
      </li>
      <li><a href="#css">CSS</a>
        <ul>
          <li><a href="#css-syntax">CSS syntax</a></li>
          <li><a href="#css-declaration-order">Declaration order</a></li>
          <li><a href="#css-media-queries">Media query placement</a></li>
          <li><a href="#css-prefixed-properties">Prefixed properties</a></li>
          <li><a href="#css-single-declarations">Rules with single declarations</a></li>
        </ul>
      </li>
    </ul>
  </div>
  <div class="col">
    <ul>
      <li><a href="#human-readable">Human readable</a>
        <ul>
          <li><a href="#comments">Comments</a></li>
          <li><a href="#classes">Classes</a></li>
          <li><a href="#selectors">Selectors</a></li>
        </ul>
      </li>
      <li><a href="#organization">Organization</a></li>
      <li><a href="#copy">Copy</a>
        <ul>
          <li><a href="#copy-sentence-case">Sentence case</a></li>
        </ul>
      </li>
    </ul>
  </div>
</div>


<div class="section">
  <div class="col">
    <h2>Golden rule</h2>
    <p>Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what's incorrect. For additions or contributions to this Code Guide, please <a href="https://github.com/mdo/code-guide/issues/new">open an issue on GitHub</a>.</p>
  </div>
  <div class="col">
    <blockquote>
      <p>Every line of code should appear to be written by a single person, no matter the number of contributors.</p>
    </blockquote>
  </div>
</div>



<div class="heading" id="html">
  <h2>HTML</h2>
</div>

<div class="section" id="html-syntax">
  <div class="col">
    <h3>Syntax</h3>
    <ul>
      <li>Use soft-tabs with two spaces</li>
      <li>Nested elements should be indented once (2 spaces)</li>
      <li>Always use double quotes, never single quotes</li>
      <li>Don't include a trailing slash in self-closing elements</li>
    </ul>
  </div>
  <div class="col">
    {% highlight html %}{% include html/syntax.html %}{% endhighlight %}
  </div>
</div>

<div class="section" id="html-doctype">
  <div class="col">
    <h3>HTML5 doctype</h3>
    <p>Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.</p>
  </div>
  <div class="col">
    {% highlight html %}{% include html/doctype.html %}{% endhighlight %}
  </div>
</div>

<div class="section" id="html-practicality">
  <div class="col">
    <h3>Practicality over purity</h3>
    <p>Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.</p>
  </div>
</div>

<div class="section" id="html-attribute-order">
  <div class="col">
    <h3>Attribute order</h3>
    <p>HTML attributes should come in this particular order for easier reading of code.</p>
    <ul>
      <li><code>class</code></li>
      <li><code>id</code></li>
      <li><code>data-*</code></li>
      <li><code>src</code>, <code>for</code>, <code>type</code>, <code>href</code></li>
    </ul>
  </div>
  <div class="col">
    {% highlight html %}{% include html/attribute-order.html %}{% endhighlight %}
  </div>
</div>

<div class="section" id="html-boolean-attributes">
  <div class="col">
    <h3>Boolean attributes</h3>
    <p>A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.</p>
    <p>For further reading, consult the <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/common-microsyntaxes.html#boolean-attributes">WhatWG section on boolean attributes</a>:</p>
    <blockquote>
      <p>The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.</p>
    </blockquote>
    <p>If you <em>must</em> include the attribute's value, and <strong>you don't need to</strong>, follow this WhatWG guideline:</p>
    <blockquote>
      <p>If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace.</p>
    </blockquote>
    <p>In short, don't add a value.</p>
  </div>
  <div class="col">
    {% highlight html %}{% include html/boolean-attributes.html %}{% endhighlight %}
  </div>
</div>

<div class="section" id="html-reducing-markup">
  <div class="col">
    <h3>Reducing markup</h3>
    <p>Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:</p>
  </div>
  <div class="col">
    {% highlight html %}{% include html/reducing-markup.html %}{% endhighlight %}
  </div>
</div>

<div class="section" id="html-javascript">
  <div class="col">
    <h3>JavaScript generated markup</h3>
    <p>Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.</p>
  </div>
</div>




<div class="heading" id="css">
  <h2>CSS</h2>
</div>

<div class="section" id="css-syntax">
  <div class="col">
    <h3>Syntax</h3>
    <ul>
      <li>Use soft-tabs with two spaces.</li>
      <li>When grouping selectors, keep individual selectors to a single line.</li>
      <li>Include one space before the opening brace of declaration blocks.</li>
      <li>Place closing braces of declaration blocks on a new line.</li>
      <li>Include one space after <code>:</code> for each declaration.</li>
      <li>Each declaration should appear on its own line for more accurate error reporting.</li>
      <li>End all declarations with a semi-colon.</li>
      <li>Comma-separated values should include a space after each comma.</li>
      <li>Don't include spaces after commas <em>within</em> <code>rgb()</code> or <code>rgba()</code> colors, and don't preface values with a leading zero.</li>
      <li>Lowercase all hex values, e.g., <code>#fff</code>.</li>
      <li>Use shorthand hex values where available, e.g., <code>#fff</code> instead of <code>#ffffff</code>.</li>
      <li>Quote attribute values in selectors, e.g., <code>input[type="text"]</code>.</li>
      <li>Avoid specifying units for zero values, e.g., <code>margin: 0;</code> instead of <code>margin: 0px;</code>.</li>
    </ul>
    <p>Questions on the terms used here? See the <a href="http://en.wikipedia.org/wiki/Cascading_Style_Sheets#Syntax">syntax section of the Cascading Style Sheets article</a> on Wikipedia.</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/syntax.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-declaration-order">
  <div class="col">
    <h3>Declaration order</h3>
    <p>Related declarations should be grouped together, placing positioning and box-model properties closest to the top, followed by typographic and visual properties.</p>
    <p>For a complete list of properties and their order, please see <a href="http://twitter.github.com/recess">Recess</a>.</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/declaration-order.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-media-queries">
  <div class="col">
    <h3>Media query placement</h3>
    <p>Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future. Here's a typical setup.</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/media-queries.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-prefixed-properties">
  <div class="col">
    <h3>Prefixed properties</h3>
    <p>When using vendor prefixed properties, indent each property such that the declaration's value lines up vertically for easy multi-line editing.</p>
    <p>In Textmate, use <strong>Text &rarr; Edit Each Line in Selection</strong> (&#8963;&#8984;A). In Sublime Text 2, use <strong>Selection &rarr; Add Previous Line</strong> (&#8963;&#8679;&uarr;) and <strong>Selection &rarr;  Add Next Line</strong> (&#8963;&#8679;&darr;).</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/prefixed-properties.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-single-declarations">
  <div class="col">
    <h3>Single declarations</h3>
    <p>In instances where a rule set includes only one declaration, consider removing line breaks for readability and faster editing. Consider this mixed example:</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/single-declarations.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-nesting">
  <div class="col">
    <h3>Nesting in LESS and SASS</h3>
    <p>Avoid unnecessary nesting. Just because you can nest, doesn't mean you always should. Consider nesting if you must scope styles to a parent and if there are multiple elements to be nested.</p>
  </div>
  <div class="col">
    {% highlight scss %}{% include css/nesting.scss %}{% endhighlight %}
  </div>
</div>

<div class="heading" id="css-human-readable">
  <h2>Human readable</h3>
</div>

<div class="section" id="css-comments">
  <div class="col">
    <h3>Comments</h3>
    <p>Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.</p>
    <p>Great code comments convey context or purpose and should not just reiterate a component or class name.</p>
  </div>
  <div class="col">
    {% highlight css %}{% include css/comments.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-class-names">
  <div class="col">
    <h3>Class names</h3>
    <ul>
      <li>Keep classes lowercase and use dashes (not underscores or camelCase).</li>
      <li>Avoid arbitrary shorthand notation.</li>
      <li>Keep classes as short and succinct as possible.</li>
      <li>Use meaningful names; use structural or purposeful names over presentational.</li>
      <li>Prefix classes based on the closest parent component's base class.</li>
    </ul>
  </div>
  <div class="col">
    {% highlight css %}{% include css/class-names.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-selectors">
  <div class="col">
    <h3>Selectors</h3>
    <ul>
      <li>Use classes over generic element tags.</li>
      <li>Keep them short and limit the number of elements in each selector to three.</li>
      <li>Scope classes to the closest <strong>only</strong> parent when necessary (e.g., when not using prefixed classes).</li>
    </ul>
    <p>Additional reading:</p>
    <ul>
      <li><a href="http://markdotto.com/2012/02/16/scope-css-classes-with-prefixes/">Scope CSS classes with prefixes</a></li>
      <li><a href="http://markdotto.com/2012/03/02/stop-the-cascade/">Stop the cascade</a></li>
    </ul>
  </div>
  <div class="col">
    {% highlight css %}{% include css/selectors.css %}{% endhighlight %}
  </div>
</div>

<div class="section" id="css-organization">
  <div class="col">
    <h3>Organization</h3>
    <ul>
      <li>Organize sections of code by component.</li>
      <li>Develop a consistent commenting hierarchy.</li>
      <li>If using multiple CSS files, break them down by component.</li>
    </ul>
  </div>
</div>

<div class="section" id="css-editor-prefs">
  <div class="col">
    <h3>Editor preferences</h3>
    <p>Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:</p>
    <ul>
      <li>Use soft-tabs set to 2 spaces</li>
      <li>Trim trailing white space on save</li>
      <li>Set encoding to UTF-8</li>
      <li>Add new line at end of files</li>
    </ul>
    <p>Consider applying these preferences to your project's <code>.editorconfig</code> file, a la <a href="https://github.com/twbs/bootstrap/blob/master/.editorconfig">Bootstrap's own</a>.</p>
  </div>
</div>


<div class="heading" id="copy">
  <h2 id="copy">Copy</h2>
</div>

<div class="section" id="copy-sentence-case">
  <div class="col">
    <h3>Sentence case</h3>
    <p>Always write copy, including headings and code comments, in <a href="http://en.wikipedia.org/wiki/Letter_case#Usage">sentence case</a>. In other words, aside from titles and proper nouns, only the first word should be capitalized.</p>
  </div>
</div>