Made some changes to some of the standards.

stanosmith · Mar 6, 2014 · 5caf71b · 5caf71b
1 parent d339314
commit 5caf71b
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 46 deletions.
diff --git a/_config.yml b/_config.yml
@@ -1,14 +1,14 @@
 ## These are overriden by GitHub
-#safe:         true
-#lsi: false
-#pygments: true
-#source: your top-level directory
+#safe:          true
+#lsi:           false
+#pygments:      true
+#source:        your top-level directory
 
-name:          Code Guide by @wirestone_ux
+name:          Coding Standards & Style Guide
 description:   Standards for developing flexible, durable, and sustainable HTML and CSS.
 url:           http://stanosmith.github.com/code-guide
 
 markdown:      rdiscount
 permalink:     pretty
 pygments:      true
-exclude: [node_modules, Gruntfile.js, package.json]
+exclude:      [node_modules, Gruntfile.js, package.json]
diff --git a/_includes/html/attribute-order.html b/_includes/html/attribute-order.html
@@ -1,4 +1,4 @@
-<a class="..." id="..." data-modal="toggle" href="#">
+<a id="..." class="..." data-modal="toggle" href="#">
   Example link
 </a>
 

diff --git a/index.html b/index.html
@@ -3,7 +3,7 @@
 ---
 
 
-<div class="heading" id="toc">
+<div id="toc" class="heading">
   <h2>Table of contents</h2>
 </div>
 <div class="section toc">
@@ -24,7 +24,7 @@ <h4><a href="#html">HTML</a></h4>
   <div class="col">
     <h4><a href="#css">CSS</a></h4>
     <ul>
-      <li><a href="#css-syntax">CSS syntax</a></li>
+      <li><a href="#css-syntax">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>
@@ -34,35 +34,31 @@ <h4><a href="#css">CSS</a></h4>
       <li><a href="#css-classes">Classes</a></li>
       <li><a href="#css-selectors">Selectors</a></li>
       <li><a href="#css-organization">Organization</a></li>
+      <li><a href="#css-editor-prefs">Editor Preferences</a></li>
     </ul>
   </div>
 </div>
 
 
-<div class="section" id="golden-rule">
+<div id="golden-rule" 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/stanosmith/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>
+    <p>Every line of code should appear to be written by a single person, no matter the number of contributors.</p>
   </div>
 </div>
 
 
 
-<div class="heading" id="html">
+<div id="html" class="heading">
   <h2>HTML</h2>
 </div>
 
-<div class="section" id="html-syntax">
+<div id="html-syntax" class="section">
   <div class="col">
     <h3>Syntax</h3>
     <ul>
-      <li>Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.</li>
-      <li>Nested elements should be indented once (two spaces).</li>
+      <li>Use soft tabs (spaces)—they're the only way to guarantee code renders the same in any environment.</li>
+      <li>Nested elements should be indented (one soft tab).</li>
       <li>Always use double quotes, never single quotes, on attributes.</li>
       <li>Don't include a trailing slash in self-closing elements—the <a href="http://dev.w3.org/html5/spec-author-view/syntax.html#syntax-start-tag">HTML5 spec</a> says they're optional.</li>
     </ul>
@@ -72,7 +68,7 @@ <h3>Syntax</h3>
   </div>
 </div>
 
-<div class="section" id="html-doctype">
+<div id="html-doctype" class="section">
   <div class="col">
     <h3>HTML5 doctype</h3>
     <p>Enforce standards mode and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page.</p>
@@ -82,7 +78,7 @@ <h3>HTML5 doctype</h3>
   </div>
 </div>
 
-<div class="section" id="html-encoding">
+<div id="html-encoding" class="section">
   <div class="col">
     <h3>Character encoding</h3>
     <p>Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding.</p>
@@ -92,7 +88,7 @@ <h3>Character encoding</h3>
   </div>
 </div>
 
-<div class="section" id="html-style-script">
+<div id="html-style-script" class="section">
   <div class="col">
     <h3>CSS and JavaScript includes</h3>
     <p>Per HTML5 spec, typically there is no need to specify a <code>type</code> when including CSS and JavaScript files as <code>text/css</code> and <code>text/javascript</code> are their respective defaults.</p>
@@ -108,31 +104,31 @@ <h4>HTML5 spec links</h4>
   </div>
 </div>
 
-<div class="section" id="html-practicality">
+<div id="html-practicality" class="section">
   <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 id="html-attribute-order" class="section">
   <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>id</code></li>
       <li><code>class</code></li>
-      <li><code>id</code>, <code>name</code></li>
       <li><code>data-*</code></li>
-      <li><code>src</code>, <code>for</code>, <code>type</code>, <code>href</code></li>
+      <li><code>src</code>, <code>name</code>, <code>for</code>, <code>type</code>, <code>href</code></li>
     </ul>
-    <p>Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second.</p>
+    <p>IDs are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come first. Classes make for great reusable components, so they come second.</p>
   </div>
   <div class="col">
     {% highlight html %}{% include html/attribute-order.html %}{% endhighlight %}
   </div>
 </div>
 
-<div class="section" id="html-boolean-attributes">
+<div id="html-boolean-attributes" class="section">
   <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>
@@ -151,7 +147,7 @@ <h3>Boolean attributes</h3>
   </div>
 </div>
 
-<div class="section" id="html-reducing-markup">
+<div id="html-reducing-markup" class="section">
   <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>
@@ -161,7 +157,7 @@ <h3>Reducing markup</h3>
   </div>
 </div>
 
-<div class="section" id="html-javascript">
+<div id="html-javascript" class="section">
   <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>
@@ -170,16 +166,16 @@ <h3>JavaScript generated markup</h3>
 
 
 
-<div class="heading" id="css">
+<div id="css" class="heading">
   <h2>CSS</h2>
 </div>
 
-<div class="section" id="css-syntax">
+<div id="css-syntax" class="section">
   <div class="col">
     <h3>Syntax</h3>
     <ul>
-      <li>Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.</li>
-      <li>When grouping selectors, keep individual selectors to a single line.</li>
+      <li>Use soft tabs (spaces)—they're the only way to guarantee code renders the same in any environment.</li>
+      <li>When grouping selectors, put each selector on a new line.</li>
       <li>Include one space before the opening brace of declaration blocks for legibility.</li>
       <li>Place closing braces of declaration blocks on a new line.</li>
       <li>Include one space after <code>:</code> for each declaration.</li>
@@ -199,7 +195,7 @@ <h3>Syntax</h3>
   </div>
 </div>
 
-<div class="section" id="css-declaration-order">
+<div id="css-declaration-order" class="section">
   <div class="col">
     <h3>Declaration order</h3>
     <p>Related property declarations should be grouped together following the order:</p>
@@ -218,7 +214,7 @@ <h3>Declaration order</h3>
   </div>
 </div>
 
-<div class="section" id="css-media-queries">
+<div id="css-media-queries" class="section">
   <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>
@@ -228,7 +224,7 @@ <h3>Media query placement</h3>
   </div>
 </div>
 
-<div class="section" id="css-prefixed-properties">
+<div id="css-prefixed-properties" class="section">
   <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>
@@ -239,7 +235,7 @@ <h3>Prefixed properties</h3>
   </div>
 </div>
 
-<div class="section" id="css-single-declarations">
+<div id="css-single-declarations" class="section">
   <div class="col">
     <h3>Single declarations</h3>
     <p>In instances where a rule set includes <storng>only one declaration</strong>, consider removing line breaks for readability and faster editing. Any rule set with multiple declarations should be split to separate lines.</p>
@@ -250,7 +246,7 @@ <h3>Single declarations</h3>
   </div>
 </div>
 
-<div class="section" id="css-shorthand">
+<div id="css-shorthand" class="section">
   <div class="col">
     <h3>Shorthand notation</h3>
     <p>Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. Common overused shorthand properties include:</p>
@@ -270,17 +266,18 @@ <h3>Shorthand notation</h3>
   </div>
 </div>
 
-<div class="section" id="css-nesting">
+<div id="css-nesting" class="section">
   <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 only if you must scope styles to a parent and if there are multiple elements to be nested.</p>
+    <p>This will also help us avoid creating <a href="http://csswizardry.com/2012/11/code-smells-in-css/">smelly code</a> and <a href="http://snook.ca/archives/html_and_css/understanding_c">specificity issues</a>.</p>
   </div>
   <div class="col">
     {% highlight scss %}{% include css/nesting.scss %}{% endhighlight %}
   </div>
 </div>
 
-<div class="section" id="css-comments">
+<div id="css-comments" class="section">
   <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. Great code comments convey context or purpose. Do not simply reiterate a component or class name.</p>
@@ -291,7 +288,7 @@ <h3>Comments</h3>
   </div>
 </div>
 
-<div class="section" id="css-classes">
+<div id="css-classes" class="section">
   <div class="col">
     <h3>Class names</h3>
     <ul>
@@ -308,7 +305,7 @@ <h3>Class names</h3>
   </div>
 </div>
 
-<div class="section" id="css-selectors">
+<div id="css-selectors" class="section">
   <div class="col">
     <h3>Selectors</h3>
     <ul>
@@ -328,7 +325,7 @@ <h3>Selectors</h3>
   </div>
 </div>
 
-<div class="section" id="css-organization">
+<div id="css-organization" class="section">
   <div class="col">
     <h3>Organization</h3>
     <ul>
@@ -343,7 +340,7 @@ <h3>Organization</h3>
   </div>
 </div>
 
-<div class="section" id="css-editor-prefs">
+<div id="css-editor-prefs" class="section">
   <div class="col">
     <h3>Editor preferences</h3>
     <p>Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:</p>