forked from isobar-us/code-standards
-
Notifications
You must be signed in to change notification settings - Fork 0
/
nglayout.html
339 lines (325 loc) · 22.8 KB
/
nglayout.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
<!doctype html>
<!--[if lt IE 7]> <html lang="nglayout" class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html lang="nglayout" class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html lang="nglayout" class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html lang="nglayout" class="no-js"> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Front-end Code Standards &amp; Best Practices | Isobar</title>
<meta name="description" content="Isobar's Coding Standards and Frontend development Best Practices">
<meta name="keywords" content="Isobar code standards, coding standards, frontend development, frontend best practices, html code standards, html5 code standards, css code standards, best code practices, development, frontend development">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="favicon.ico"/>
<link rel="apple-touch-icon-precomposed" href="ios-icon.png"/>
<link rel="stylesheet" href="css/generated/style.css">
<!--
_^_
/ _)
.-^^^-/ / we like dinosaurs as much as you do.
__/ /
<__.|_|-|_|
-->
<script src="js/libs/modernizr-1.7.min.js"></script>
</head>
<body>
<a class="fork" href="https://github.com/isobar-idev/code-standards/" target="_blank"></a>
<div id="container">
<header role=banner>
<h1><a id="logo" href="http://www.isobar.com/us/home">Isobar</a></h1>
<ul id="social">
<li><a class="icon" href="http://www.shareaholic.com/api/share/?v=1&apitype=1&apikey=8943b7fd64cd8b1770ff5affa9a9437b&service=5&title=Isobar%20North%20America's%20Coding%20Standards%20and%20Frontend%20development%20Best%20Practices&link=http://na.isobar.com/standards/&source=Shareaholic" id="facebook"></a></li>
<li><a class="icon" href="http://www.shareaholic.com/api/share/?v=1&apitype=1&apikey=8943b7fd64cd8b1770ff5affa9a9437b&service=7&title=Isobar%20North%20America's%20Coding%20Standards%20and%20Frontend%20development%20Best%20Practices&link=http://na.isobar.com/standards/&source=Shareaholic" id="twitter"></a></li>
<li><a class="icon" href="http://www.shareaholic.com/api/share/?v=1&apitype=1&apikey=8943b7fd64cd8b1770ff5affa9a9437b&service=2&title=Isobar%20North%20America's%20Coding%20Standards%20and%20Frontend%20development%20Best%20Practices&link=http://na.isobar.com/standards/&source=Shareaholic" id="delicious"></a></li>
<li><a href="http://www.isobar.com/us/home" id="linkback">Return to Isobar</a></li>
</ul>
</header>
<div id="main" role="document">
<article>
<section><h1 id="front-end-code-standards">Front-End Code Standards</h1>
<h2 id="general">General</h2>
<p>This document contains the formatting guidelines and best practices for the front-end web development team at Isobar. There are many ways of leveraging HTML, CSS, and JavaScript to create a website - each item here represents either (1) a decision we've made favoring one method over its alternatives or (2) a reminder to follow existing standards. What this document is <em>not</em> is a series of explanations as to how front-end technologies work; a basic familiarity is assumed. It also does <em>not</em> provide evaluations of the pros and cons of various alternatives; we pick what we consider to be the best one and run with it. Any issues that don't yet have a clear solution are not listed here.</p>
<p>Our motivations in creating this document are to (1) foster code consistency across our projects to facilitate ease of maintenance and onboarding and (2) educate new developers on how best to create robust, performant, and accessible websites.</p>
<h3 id="goals">Goals</h3>
<ul>
<li>Consistency</li>
<li>Professional standards</li>
<li>Pillars of Front-end Development</li>
<li>Architectural thinking</li>
</ul>
<h3 id="getting-started">Getting Started</h3>
<ul>
<li>Identify Deliverables</li>
<li>Development vs Production</li>
<li>Browser and device requirements </li>
</ul>
<h3 id="general-standards">General Standards</h3>
<ul>
<li>Compression</li>
<li>Maintainabilty</li>
<li>Readability</li>
<li>Comments</li>
</ul>
<p>(redundant below)</p>
<h3 id="formatting">Formatting</h3>
<h4 id="indentation">Indentation</h4>
<p>For all code languages, we use soft tabs comprised of four spaces per tab. Hitting the Tab key in your text editor should generate four space characters rather than one tab character. This results in our code appearing identical across platforms.</p>
<h4 id="readability">Readability</h4>
<p>We encourage liberal use of whitespace, comments, and descriptive variable names as appropriate for writing easy-to-read code. There is no need to write code in an obfuscated or compressed way for the purpose of file-size savings; we will use automated server-side or build processes to concatenate, minify, and gzip all static client-side code (such as CSS and JavaScript).</p>
<h3 id="next-steps">Next Steps</h3>
<p>(knowledge transfer?)</p>
<h3 id="resources">Resources</h3>
<p>Further reading on the wiki</p>
</section>
<section><h2 id="html">HTML</h2>
<p>HTML markup defines the content of a document and gives it a rudimentary structure such as headers, paragraphs, and lists. It provides a number of semantic constructs that allow automated tools like search engines and screen readers to make sense of the document and to understand relationships between pieces of content. A well-written HTML document will make appropriate use of these semantic elements and leave all responsibility for controlling the presentation of the document to the CSS stylesheet.</p>
<h3 id="goals">Goals</h3>
<ul>
<li>Consistency</li>
<li>Semantic Markup</li>
<li>Validation</li>
</ul>
<h3 id="getting-started">Getting Started</h3>
<ul>
<li>Templates </li>
<li>Frameworks</li>
</ul>
<h3 id="html-standards">HTML Standards</h3>
<ul>
<li>HTML5 <ul>
<li>Doctype</li>
<li>HTML5 Tags</li>
<li>Character Encoding</li>
<li>Validation</li>
</ul>
</li>
<li>General Markup</li>
<li>Tags<ul>
<li>Optional</li>
<li>Self-closing</li>
</ul>
</li>
<li>Attributes<ul>
<li>Quoted</li>
<li>Extending HTML5<ul>
<li>Data attributes, etc</li>
</ul>
</li>
</ul>
</li>
</ul>
<h4 id="doctype">Doctype</h4>
<p>We always include a proper doctype to trigger standards mode. Omitting the doctype triggers quirks mode and should always be avoided. The HTML5 doctype is simple and easy to remember.</p>
<pre><code><!doctype html></code></pre>
<h4 id="character-encoding">Character Encoding</h4>
<p>All markup should be delivered as UTF-8, since it has the best support for internationalization. The character encoding should be designated in both the HTTP header and the head of the document via a meta tag. If the server happens to omit the HTTP header, the browser takes a guess at the character encoding and begins parsing the markup, throwing away all that work and starting over if it encounters the meta tag and its guess was incorrect. Because of this, as a best practice, we always put the meta tag as early in the <code><head></code> tag as possible.</p>
<pre><code><meta charset="UTF-8"></code></pre>
<h4 id="attribute-values">Attribute Values</h4>
<p>We use quotes to surround all attribute values in HTML, despite quotes being optional in HTML5. This maintains consistency between attribute values that contain whitespace and those that don't.</p>
<pre><code><form class="registration module clearfix" action="/register" method="POST"></code></pre>
<h4 id="ids-vs-classes">IDs vs. Classes</h4>
<p>HTML elements can be identified by using the <code>id</code> and <code>class</code> attributes. An ID is a unique identifier for that particular element; no other element on the page should use the same ID. This uniqueness allows <code><label></code> elements to associate themselves with a particular input and URLs to jump to a particular scroll position on a page. Classes are not unique. The same class can be used on multiple elements within a page, and a single element can have more than one class.</p>
<pre><code><ul id="categories">
<li class="category">Jackets</li>
<li class="category">Accessories</li>
<li class="category">Shoes</li>
</ul></code></pre>
<p>When coming up with names for an ID or class, we use semantic names like "secondary-nav" or "primary-button" that describe what the element is, rather than names like "left-nav" or "blue-button" that describe what the element looks like, which can change over time. We also use lowercase names with hyphens separating words as opposed to camelCase or underscores. This matches the lowercase nature of HTML5 as well as the naming scheme for <code>data-xxx</code> attributes.</p>
<h4 id="use-of-html5-elements">Use of HTML5 Elements</h4>
<p>To provide additional semantic value to our documents, we make use of HTML5 elements such as <code><header></code>, <code><article></code>, and <code><section></code> where appropriate. However, in order to ensure that our HTML is as backwards-compatible as possible, we do not apply IDs or classes to them, since older browsers do not understand these elements by default and will not apply styling to them.</p>
<pre><code><header>
<div class="site-header">
...
</div>
</header></code></pre>
<h4 id="anchors">Anchors</h4>
<p>All anchor links should point to absolute or relative URLs with user-readable content. Do not link to XML or JSON resources that are designed to be Ajaxed by JavaScript instead of navigated to directly, and do not put JavaScript in an anchor's <code>href</code> attribute like <code>javascript:loadPage(2);</code>. This allows search engines to index the content, allows the user to open the links in a new tab or window, and means the links will still work when JavaScript is broken, disabled, or not supported. This will require that the back-end be able to return a full HTML page for each important content state (e.g. sorting a table column).</p>
<h4 id="paragraphs">Paragraphs</h4>
<p>Avoid using <code><br /></code> tags to separate paragraphs or lines of text. Use <code><p></code> instead.</p>
<h4 id="definition-lists">Definition Lists</h4>
<p>We use definition lists to display a single record of name-value pairs, like a contact card.</p>
<h4 id="tables">Tables</h4>
<p>Tables should not be used for page layout; only use them when you need to display tabular data. They provide an important semantic association (used mostly by screen readers for the sight-impaired) between row/column headers and their data, so use <code><table></code> rather than other elements when displaying multiple records of data.</p>
<p>The <code><caption></code> element is the recommended way to describe a table for both sighted and sight-impaired users, though this can also be done less semantically in the normal page text around the table. We use the <code><thead></code> and <code><tbody></code> elements to denote which row contains column headers so when a user prints the website and the table runs onto another page, browsers can display the <code><thead></code> on each page for easier readability. Remember to use the <code>scope</code> attribute on the <code><th></code> element to indicate whether the header applies to the row or column.</p>
<pre><code><table>
<caption>First two U.S. presidents</caption>
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Took office</th>
<th scope="col">Party</th>
</tr>
</thead>
<tbody>
<tr>
<td>George Washington</td>
<td>April 30, 1789</td>
<td>n/a</td>
</tr>
<tr>
<td>John Adams</td>
<td>March 4, 1797</td>
<td>Federalist</td>
</tr>
</tbody>
</table></code></pre>
<h4 id="forms">Forms</h4>
<p>For both semantic and functional reasons, we make full use of the <code><form></code> tag for all sections requiring user input. All form <code>action</code> attributes should point to URLs with user-readable content, so they will still work if the form is submitted by the user before JavaScript has loaded on a page, or if JavaScript is broken, disabled, or not supported. This will require that the back-end be able to return a full HTML page for form submission (e.g. registering a new user, editing the quantity in a shopping cart).</p>
<h4 id="input-labels">Input Labels</h4>
<p>All input fields should be associated with a <code><label></code> element. The <code>for</code> attribute of the <code><label></code> element should contain the ID of the corresponding input field. This means the input field will receive focus when a user clicks the label and also enables screen readers for sight-impaired users to read out an appropriate description of the input field.</p>
<pre><code><label for="home-address">Home Address</label>
<input id="home-address" type="text" /></code></pre>
<h3 id="next-steps">Next Steps</h3>
<ul>
<li>Templates</li>
<li>Break down (CMS, templates, re-use)</li>
</ul>
<h3 id="resources">Resources</h3>
<p>Further information on the wiki...</p>
</section>
<section><h2 id="css">CSS</h2>
<p>CSS is where the visual presentation logic of a website belongs. Well-written CSS makes good use of its cascading nature - general styles are applied first, and those styles are overridden for more specific instances as necessary.</p>
<h3 id="goals">Goals</h3>
<ul>
<li>General coding principles<ul>
<li>Customization / Maintainabilty</li>
<li>Components / Modules / OOCSS</li>
</ul>
</li>
</ul>
<h3 id="getting-started">Getting Started</h3>
<ul>
<li>Grids</li>
<li>Frameworks</li>
</ul>
<h3 id="css-standards">CSS Standards</h3>
<h4 id="inclusion">Inclusion</h4>
<p>Use the <code><link></code> tag to include all your stylesheets in the <code><head></code> of the document. For optimal page performance, concatenate your CSS into as few files as possible and do not use the <code>@import</code> command to include other stylesheets, as this will fire an additional HTTP request and block page rendering until its completion.</p>
<pre><code><link rel="stylesheet" type="text/css" href="main.css" /></code></pre>
<h4 id="inline-styling">Inline Styling</h4>
<p>Do not put styling information into your HTML markup directly, either with the <code>style</code> attribute that accepts CSS or with deprecated attributes such as <code>align</code>, <code>border</code>, or <code>width</code>. These are difficult to maintain and make it harder to track down what is causing an element to appear as it does.</p>
<h4 id="formatting">Formatting</h4>
<p>We put each selector on its own line and each property on its own line for easy readability and so version control systems can clearly show which parts have changed. The attributes within a selector should be alphabetized for easy scanning and so that compression algorithms like gzip have a greater chance of finding repeatable patterns.</p>
<pre><code>#content {
margin-left: -2%;
}
.most-popular,
.my-favorites,
.twitter-feed {
float: left;
padding-left: 2%;
width: 33.3333333%;
}</code></pre>
<p>We do not indent child styles underneath their parent styles for a few reasons. When scanning through a CSS file to locate media queries, we generally look for indented styles, so indenting selectors that are not within a media query causes confusion. It also hinders maintainability. HTML and CSS structure can change frequently over the course of a project, quickly rendering obsolete the parent-child relationship the indentation used to represent. And the more levels of indentation there are, the harder it is to update.</p>
<h4 id="box-model">Box Model</h4>
<p>To simplify CSS authoring, we set the <code>box-sizing</code> attribute to <code>border-box</code> for all page elements. This enables us to use round numbers for width like 50% and then apply a padding or border to that same element without needing to (1) adjust the width accordingly using calc (since borders use pixels rather than percents) or (2) create an element inside it to take the padding and border. This is the only case where we use the inefficient universal selector (<code>*</code>).</p>
<pre><code>* {
-moz-box-sizing: border-box;
-webkit-box-sizing: border-box;
box-sizing: border-box;
}</code></pre>
<h4 id="specificity">Specificity</h4>
<p>CSS is most efficient when its selectors are <a href="https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Writing_efficient_CSS">extremely specific with limited DOM traversal involved</a>. The ID is the most specific selector, since it can only match one element, and the class is a close second. Use those whenever possible rather than HTML tag names.</p>
<p>The descendant selector (the space character) is the most expensive selector in CSS. The child selector (the "<code>></code>" character) is also expensive, especially when the rules are tag names rather than classes or IDs. Avoid both. Try applying a class to the element you want to target instead.</p>
<pre><code>/* BAD */
button#back-button { ... }
.popular ul li a { ... }
.popular > ul > li > a { ... }
/* GOOD */
#back-button { ... }
.popular-link { ... }
.popular-link { ... }</code></pre>
<p>Avoid using the <code>!important</code> keyword. Treat it like the nuclear option, only to be used in the most extreme of cases. There is usually another way to achieve the same goal without causing headaches for developers in the future who are either trying to debug a styling issue or trying to use normal specificity to override a style for a particular element only to find that they can't.</p>
<h3 id="next-steps">Next Steps</h3>
<ul>
<li>Compatibility</li>
<li>Internet Explorer Bugs</li>
<li>Use CSS3</li>
<li>Color Management</li>
</ul>
<h3 id="resources">Resources</h3>
<p>Further reading on the wiki etc.</p>
</section>
<section><h2 id="javascript">JavaScript</h2>
<h3 id="goals">Goals</h3>
<h3 id="getting-started">Getting Started</h3>
<ul>
<li>JavaScript Libraries</li>
</ul>
<h3 id="javascript-standards">JavaScript Standards</h3>
<h4 id="inclusion">Inclusion</h4>
<p>Use the <code><script></code> tag to include your JavaScript files at the bottom of your HTML document just before the closing <code></body></code> tag. For optimal page performance, concatenate your JavaScript into as few files as possible.</p>
<pre><code><script type="text/javascript" src="main.js"></script></code></pre>
<h4 id="formatting">Formatting</h4>
<p>The use of whitespace should follow long-standing English writing conventions. Specifically, each comma and colon (and semi-colons that don't end a line) should be followed by a single space. Binary and ternary operators should have a single space on each side. There should be no space characters between parentheses and their contents. Opening braces should appear on the same line as their preceding argument.</p>
<pre><code>for (var i = 0, len = arr.length; i < len; i++) {
// do something
}</code></pre>
<p>To maximize readability without worrying about which boolean operators bind more tightly than others, each segment of a boolean expression should be enclosed in parentheses.</p>
<pre><code>if ((allowUpdate) && ((user.isAdmin) || (user.role === item.owner))) {
// do something
}</code></pre>
<h4 id="variable-declaration">Variable Declaration</h4>
<p>To avoid confusion between global and local variables, we declare each variable on its own line with the <code>var</code> keyword. We do not use a single <code>var</code> keyword and then chain several variable declarations onto it separated by a comma.</p>
<pre><code>var currentVal = $(this).val();
var min = parseInt($(this).attr('min'), 10);
var max = parseInt($(this).attr('max'), 10);</code></pre>
<h4 id="feature-detection">Feature Detection</h4>
<p>Always test for the existence of a browser API, function, or object property before you use it, and make sure the user experience is still functional (to the extent possible) if it's not found. We rely on JavaScript-based feature detection rather than server-side device detection because it's more robust, easily maintained, and future-proof.</p>
<h3 id="next-steps">Next Steps</h3>
<ul>
<li>Debugging</li>
<li>Patterns for Better JavaScript</li>
<li>Unit Testing</li>
<li>Node.js</li>
</ul>
<h3 id="resources">Resources</h3>
<ul>
<li>Links to wiki, etc.</li>
</ul>
</section>
<section><h2 id="responsive-web-design">Responsive Web Design</h2>
<p>(Get notes from nring)</p>
<h3 id="goals">Goals</h3>
<p>...</p>
<h3 id="getting-started">Getting Started</h3>
<p>...</p>
<h3 id="standards-for-responsive-web-development">Standards For Responsive Web Development</h3>
<p>...</p>
<h3 id="next-steps">Next Steps</h3>
<p>... </p>
<h3 id="resources">Resources</h3>
<p> Link to wiki... </p>
</section>
<section><h2 id="performance">Performance</h2>
<h3 id="goals">Goals</h3>
<p>... </p>
<h3 id="getting-started">Getting Started</h3>
<p>...</p>
<h3 id="standards">Standards</h3>
<p>...</p>
<h3 id="next-steps">Next Steps</h3>
<p>...</p>
<h3 id="resources">Resources</h3>
</section>
</article>
</div>
<nav id="side" class="nav-right" role="navigation">
<h3 class="toc-title">Table of Contents</h3>
<ul id="toc" style="display:none"></ul>
<noscript><p><a href="http://enable-javascript.com">Please enable JavaScript</a>.</p></noscript>
</nav>
</div>
<footer role="contentinfo">
<p>
<span class="float_left">2014 Isobar, All rights reserved.</span>
<span class="float_right">All content licensed under Creative Commons Attribution 3.0 Unported License</span>
</p>
</footer>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
<script>window.jQuery||document.write("<script src='js/jquery-1.7.2.min.js'>\x3C/script>");</script>
<script src='js/plugins.min.js'></script>
<script defer src='js/script.js'></script>
<script>var _gaq=[["_setAccount","UA-1745698-2"],["_trackPageview"]];(function(e,a){var c=e.createElement(a),b=e.getElementsByTagName(a)[0];c.async=1;c.src=("https:"==location.protocol?"//ssl":"//www")+".google-analytics.com/ga.js";b.parentNode.insertBefore(c,b)}(document,"script"));</script>
</body>
</html>