├── .editorconfig
├── LICENSE
└── README.md


/.editorconfig:
--------------------------------------------------------------------------------
 1 | # editorconfig.org
 2 | root = true
 3 | 
 4 | [*]
 5 | indent_style = space
 6 | indent_size = 2
 7 | end_of_line = lf
 8 | charset = utf-8
 9 | trim_trailing_whitespace = true
10 | insert_final_newline = true
11 | 
12 | [*.md]
13 | trim_trailing_whitespace = false
14 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright © 2014 Nicolas Bevacqua
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 6 | this software and associated documentation files (the "Software"), to deal in
 7 | the Software without restriction, including without limitation the rights to
 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # function qualityGuide () {
  2 | 
  3 | > A **quality conscious** and _organic_ JavaScript quality guide
  4 | 
  5 | This style guide aims to provide the ground rules for an application's JavaScript code, such that it's highly readable and consistent across different developers on a team. The focus is put on quality and coherence across the different pieces of your application.
  6 | 
  7 | ## Goal
  8 | 
  9 | These suggestions aren't set in stone, they aim to provide a baseline you can use in order to write more consistent codebases. To maximize effectiveness, share the styleguide among your co-workers and attempt to enforce it. Don't become obsessed about code style, as it'd be fruitless and counterproductive. Try and find the sweet spot that makes everyone in the team comfortable developing for your codebase, while not feeling frustrated that their code always fails automated style checking because they added a single space where they weren't supposed to. It's a thin line, but since it's a very personal line I'll leave it to you to do the drawing.
 10 | 
 11 | > Use together with [bevacqua/css][32] for great good!
 12 | 
 13 | Feel free to fork this style guide, or better yet, send [Pull Requests][33] this way!
 14 | 
 15 | ## Table of Contents
 16 | 
 17 | 1. [Modules](#modules)
 18 | 2. [Strict Mode](#strict-mode)
 19 | 3. [Spacing](#spacing)
 20 | 4. [Semicolons](#semicolons)
 21 | 5. [Style Checking](#style-checking)
 22 | 6. [Linting](#linting)
 23 | 7. [Strings](#strings)
 24 | 8. [Variable Declaration](#variable-declaration)
 25 | 9. [Conditionals](#conditionals)
 26 | 10. [Equality](#equality)
 27 | 11. [Ternary Operators](#ternary-operators)
 28 | 12. [Functions](#functions)
 29 | 13. [Prototypes](#prototypes)
 30 | 14. [Object Literals](#object-literals)
 31 | 15. [Array Literals](#array-literals)
 32 | 16. [Regular Expressions](#regular-expressions)
 33 | 17. [`console` Statements](#console-statements)
 34 | 18. [Comments](#comments)
 35 | 19. [Variable Naming](#variable-naming)
 36 | 20. [Polyfills](#polyfills)
 37 | 21. [Everyday Tricks](#everyday-tricks)
 38 | 22. [License](#license)
 39 | 
 40 | ## Modules
 41 | 
 42 | This style guide assumes you're using a module system such as [CommonJS][1], [AMD][2], [ES6 Modules][3], or any other kind of module system. Modules systems provide individual scoping, avoid leaks to the `global` object, and improve code base organization by **automating dependency graph generation**, instead of having to resort to manually creating multiple `<script>` tags.
 43 | 
 44 | Module systems also provide us with dependency injection patterns, which are crucial when it comes to testing individual components in isolation.
 45 | 
 46 | ## Strict Mode
 47 | 
 48 | **Always** put [`'use strict';`][4] at the top of your modules. Strict mode allows you to catch nonsensical behavior, discourages poor practices, and _is faster_ because it allows compilers to make certain assumptions about your code.
 49 | 
 50 | ## Spacing
 51 | 
 52 | Spacing must be consistent across every file in the application. To this end, using something like [`.editorconfig`][5] configuration files is highly encouraged. Here are the defaults I suggest to get started with JavaScript indentation.
 53 | 
 54 | ```ini
 55 | # editorconfig.org
 56 | root = true
 57 | 
 58 | [*]
 59 | indent_style = space
 60 | indent_size = 2
 61 | end_of_line = lf
 62 | charset = utf-8
 63 | trim_trailing_whitespace = true
 64 | insert_final_newline = true
 65 | 
 66 | [*.md]
 67 | trim_trailing_whitespace = false
 68 | ```
 69 | 
 70 | Settling for either tabs or spaces is up to the particularities of a project, but I recommend using 2 spaces for indentation. The `.editorconfig` file can take care of that for us and everyone would be able to create the correct spacing by pressing the tab key.
 71 | 
 72 | Spacing doesn't just entail tabbing, but also the spaces before, after, and in between arguments of a function declaration. This kind of spacing is **typically highly irrelevant to get right**, and it'll be hard for most teams to even arrive at a scheme that will satisfy everyone.
 73 | 
 74 | ```js
 75 | function () {}
 76 | ```
 77 | 
 78 | ```js
 79 | function( a, b ){}
 80 | ```
 81 | 
 82 | ```js
 83 | function(a, b) {}
 84 | ```
 85 | 
 86 | ```js
 87 | function (a,b) {}
 88 | ```
 89 | 
 90 | Try to keep these differences to a minimum, but don't put much thought to it either.
 91 | 
 92 | Where possible, improve readability by keeping lines below the 80-character mark.
 93 | 
 94 | ## Semicolons`;`
 95 | 
 96 | The majority of JavaScript programmers [prefer using semicolons][6]. This choice is done to avoid potential issues with Automatic Semicolon Insertion _(ASI)_. If you decide against using semicolons, [make sure you understand the ASI rules][7].
 97 | 
 98 | Regardless of your choice, a linter should be used to catch unnecessary or unintentional semicolons.
 99 | 
100 | ## Style Checking
101 | 
102 | **Don't**. Seriously, [this is super painful][8] for everyone involved, and no observable gain is attained from enforcing such harsh policies.
103 | 
104 | ## Linting
105 | 
106 | On the other hand, linting is sometimes necessary. Again, don't use a linter that's super opinionated about how the code should be styled, like [`jslint`][9] is. Instead use something more lenient, like [`jshint`][10] or [`eslint`][11].
107 | 
108 | A few tips when using JSHint.
109 | 
110 | - Declare a `.jshintignore` file and include `node_modules`, `bower_components`, and the like
111 | - You can use a `.jshintrc` file like the one below to keep your rules together
112 | 
113 | ```json
114 | {
115 |   "curly": true,
116 |   "eqeqeq": true,
117 |   "newcap": true,
118 |   "noarg": true,
119 |   "noempty": true,
120 |   "nonew": true,
121 |   "sub": true,
122 |   "undef": true,
123 |   "unused": true,
124 |   "trailing": true,
125 |   "boss": true,
126 |   "eqnull": true,
127 |   "strict": true,
128 |   "immed": true,
129 |   "expr": true,
130 |   "latedef": "nofunc",
131 |   "quotmark": "single",
132 |   "indent": 2,
133 |   "node": true
134 | }
135 | ```
136 | 
137 | By no means are these rules the ones you should stick to, but **it's important to find the sweet spot between not linting at all and not being super obnoxious about coding style**.
138 | 
139 | ## Strings
140 | 
141 | Strings should always be quoted using the same quotation mark. Use `'` or `"` consistently throughout your codebase. Ensure the team is using the same quotation mark in every portion of JavaScript that's authored.
142 | 
143 | ##### Bad
144 | 
145 | ```js
146 | var message = 'oh hai ' + name + "!";
147 | ```
148 | 
149 | ##### Good
150 | 
151 | ```js
152 | var message = 'oh hai ' + name + '!';
153 | ```
154 | 
155 | Usually you'll be a happier JavaScript developer if you hack together a parameter-replacing method like [`util.format` in Node][12]. That way it'll be far easier to format your strings, and the code looks a lot cleaner too.
156 | 
157 | ##### Better
158 | 
159 | ```js
160 | var message = util.format('oh hai %s!', name);
161 | ```
162 | 
163 | You could implement something similar using the piece of code below.
164 | 
165 | ```js
166 | function format () {
167 |   var args = [].slice.call(arguments);
168 |   var initial = args.shift();
169 | 
170 |   function replacer (text, replacement) {
171 |     return text.replace('%s', replacement);
172 |   }
173 |   return args.reduce(replacer, initial);
174 | }
175 | ```
176 | 
177 | To declare multi-line strings, particularly when talking about HTML snippets, it's sometimes best to use an array as a buffer and then join its parts. The string concatenating style may be faster but it's also much harder to keep track of.
178 | 
179 | ```js
180 | var html = [
181 |   '<div>',
182 |     format('<span class="monster">%s</span>', name),
183 |   '</div>'
184 | ].join('');
185 | ```
186 | 
187 | With the array builder style, you can also push parts of the snippet and then join everything together at the end. This is in fact what some [string templating engines like Jade][13] prefer to do.
188 | 
189 | ## Variable Declaration
190 | 
191 | Always declare variables in **a consistent manner**, and at the top of their scope. Keeping variable declarations to _one per line is encouraged_. Comma-first, a single `var` statement, multiple `var` statements, it's all fine, just be consistent across the project, and ensure the team is on the same page.
192 | 
193 | ##### Bad
194 | 
195 | ```js
196 | var foo = 1,
197 |     bar = 2;
198 | 
199 | var baz;
200 | var pony;
201 | 
202 | var a
203 |   , b;
204 | ```
205 | 
206 | ```js
207 | var foo = 1;
208 | 
209 | if (foo > 1) {
210 |   var bar = 2;
211 | }
212 | ```
213 | ##### Good
214 | 
215 | <sub>Just because they're consistent with each other, not because of the style</sub>
216 | 
217 | ```js
218 | var foo = 1;
219 | var bar = 2;
220 | 
221 | var baz;
222 | var pony;
223 | 
224 | var a;
225 | var b;
226 | ```
227 | 
228 | ```js
229 | var foo = 1;
230 | var bar;
231 | 
232 | if (foo > 1) {
233 |   bar = 2;
234 | }
235 | ```
236 | 
237 | Variable declarations that aren't immediately assigned a value are acceptable to share the same line of code.
238 | 
239 | ##### Acceptable
240 | 
241 | ```js
242 | var a = 'a';
243 | var b = 2;
244 | var i, j;
245 | ```
246 | 
247 | ## Conditionals
248 | 
249 | **Brackets are enforced**. This, together with a reasonable spacing strategy will help you avoid mistakes such as [Apple's SSL/TLS bug][14].
250 | 
251 | ##### Bad
252 | 
253 | ```js
254 | if (err) throw err;
255 | ```
256 | 
257 | ##### Good
258 | 
259 | ```js
260 | if (err) { throw err; }
261 | ```
262 | 
263 | It's even better if you avoid keeping conditionals on a single line, for the sake of text comprehension.
264 | 
265 | ##### Better
266 | 
267 | ```js
268 | if (err) {
269 |   throw err;
270 | }
271 | ```
272 | 
273 | ## Equality
274 | 
275 | Avoid using `==` and `!=` operators, always favor `===` and `!==`. These operators are called the "strict equality operators," while [their counterparts will attempt to cast the operands][15] into the same value type.
276 | 
277 | ##### Bad
278 | 
279 | ```js
280 | function isEmptyString (text) {
281 |   return text == '';
282 | }
283 | 
284 | isEmptyString(0);
285 | // <- true
286 | ```
287 | 
288 | ##### Good
289 | 
290 | ```js
291 | function isEmptyString (text) {
292 |   return text === '';
293 | }
294 | 
295 | isEmptyString(0);
296 | // <- false
297 | ```
298 | 
299 | ## Ternary Operators
300 | 
301 | Ternary operators are fine for clear-cut conditionals, but unacceptable for confusing choices. As a rule, if you can't eye-parse it as fast as your brain can interpret the text that declares the ternary operator, chances are it's probably too complicated for its own good.
302 | 
303 | jQuery is a prime example of a codebase that's [**filled with nasty ternary operators**][16].
304 | 
305 | ##### Bad
306 | 
307 | ```js
308 | function calculate (a, b) {
309 |   return a && b ? 11 : a ? 10 : b ? 1 : 0;
310 | }
311 | ```
312 | 
313 | ##### Good
314 | 
315 | ```js
316 | function getName (mobile) {
317 |   return mobile ? mobile.name : 'Generic Player';
318 | }
319 | ```
320 | 
321 | In cases that may prove confusing just use `if` and `else` statements instead.
322 | 
323 | ## Functions
324 | 
325 | When declaring a function, always use the [function declaration form][17] instead of [function expressions][18]. Because [hoisting][19].
326 | 
327 | ##### Bad
328 | 
329 | ```js
330 | var sum = function (x, y) {
331 |   return x + y;
332 | };
333 | ```
334 | 
335 | ##### Good
336 | 
337 | ```js
338 | function sum (x, y) {
339 |   return x + y;
340 | }
341 | ```
342 | 
343 | That being said, there's nothing wrong with function expressions that are just [currying another function][20].
344 | 
345 | ##### Good
346 | 
347 | ```js
348 | var plusThree = sum.bind(null, 3);
349 | ```
350 | 
351 | Keep in mind that [function declarations will be hoisted][21] to the top of the scope so it doesn't matter the order they are declared in. That being said, you should always keep functions at the top level in a scope, and avoid placing them inside conditional statements.
352 | 
353 | ##### Bad
354 | 
355 | ```js
356 | if (Math.random() > 0.5) {
357 |   sum(1, 3);
358 | 
359 |   function sum (x, y) {
360 |     return x + y;
361 |   }
362 | }
363 | 
364 | ```
365 | 
366 | ##### Good
367 | 
368 | ```js
369 | if (Math.random() > 0.5) {
370 |   sum(1, 3);
371 | }
372 | 
373 | function sum (x, y) {
374 |   return x + y;
375 | }
376 | ```
377 | 
378 | ```js
379 | function sum (x, y) {
380 |   return x + y;
381 | }
382 | 
383 | if (Math.random() > 0.5) {
384 |   sum(1, 3);
385 | }
386 | ```
387 | 
388 | If you need a _"no-op"_ method you can use either `Function.prototype`, or `function noop () {}`. Ideally a single reference to `noop` is used throughout the application.
389 | 
390 | Whenever you have to manipulate an array-like object, cast it to an array.
391 | 
392 | ##### Bad
393 | 
394 | ```js
395 | var divs = document.querySelectorAll('div');
396 | 
397 | for (i = 0; i < divs.length; i++) {
398 |   console.log(divs[i].innerHTML);
399 | }
400 | ```
401 | 
402 | ##### Good
403 | 
404 | ```js
405 | var divs = document.querySelectorAll('div');
406 | 
407 | [].slice.call(divs).forEach(function (div) {
408 |   console.log(div.innerHTML);
409 | });
410 | ```
411 | 
412 | However, be aware that there is a [substantial performance hit][22] in V8 environments when using this approach on `arguments`. If performance is a major concern, avoid casting `arguments` with `slice` and instead use a `for` loop.
413 | 
414 | #### Bad
415 | ```js
416 | var args = [].slice.call(arguments);
417 | ```
418 | 
419 | #### Good
420 | ```js
421 | var i;
422 | var args = new Array(arguments.length);
423 | for (i = 0; i < args.length; i++) {
424 |     args[i] = arguments[i];
425 | }
426 | ```
427 | 
428 | Don't declare functions inside of loops.
429 | 
430 | ##### Bad
431 | 
432 | ```js
433 | var values = [1, 2, 3];
434 | var i;
435 | 
436 | for (i = 0; i < values.length; i++) {
437 |   setTimeout(function () {
438 |     console.log(values[i]);
439 |   }, 1000 * i);
440 | }
441 | ```
442 | 
443 | ```js
444 | var values = [1, 2, 3];
445 | var i;
446 | 
447 | for (i = 0; i < values.length; i++) {
448 |   setTimeout(function (i) {
449 |     return function () {
450 |       console.log(values[i]);
451 |     };
452 |   }(i), 1000 * i);
453 | }
454 | ```
455 | 
456 | ##### Good
457 | 
458 | ```js
459 | var values = [1, 2, 3];
460 | var i;
461 | 
462 | for (i = 0; i < values.length; i++) {
463 |   setTimeout(function (i) {
464 |     console.log(values[i]);
465 |   }, 1000 * i, i);
466 | }
467 | ```
468 | 
469 | ```js
470 | var values = [1, 2, 3];
471 | var i;
472 | 
473 | for (i = 0; i < values.length; i++) {
474 |   wait(i);
475 | }
476 | 
477 | function wait (i) {
478 |   setTimeout(function () {
479 |     console.log(values[i]);
480 |   }, 1000 * i);
481 | }
482 | ```
483 | 
484 | Or even better, just use `.forEach` which doesn't have the same caveats as declaring functions in `for` loops.
485 | 
486 | ##### Better
487 | 
488 | ```js
489 | [1, 2, 3].forEach(function (value, i) {
490 |   setTimeout(function () {
491 |     console.log(value);
492 |   }, 1000 * i);
493 | });
494 | ```
495 | 
496 | Whenever a method is non-trivial, make the effort to **use a named function declaration rather than an anonymous function**. This will make it easier to pinpoint the root cause of an exception when analyzing stack traces.
497 | 
498 | ##### Bad
499 | 
500 | ```js
501 | function once (fn) {
502 |   var ran = false;
503 |   return function () {
504 |     if (ran) { return };
505 |     ran = true;
506 |     fn.apply(this, arguments);
507 |   };
508 | }
509 | ```
510 | 
511 | ##### Good
512 | 
513 | ```js
514 | function once (fn) {
515 |   var ran = false;
516 |   return function run () {
517 |     if (ran) { return };
518 |     ran = true;
519 |     fn.apply(this, arguments);
520 |   };
521 | }
522 | ```
523 | 
524 | Avoid keeping indentation levels from raising more than necessary by using guard clauses instead of flowing `if` statements.
525 | 
526 | ##### Bad
527 | 
528 | ```js
529 | if (car) {
530 |   if (black) {
531 |     if (turbine) {
532 |       return 'batman!';
533 |     }
534 |   }
535 | }
536 | ```
537 | 
538 | ```js
539 | if (condition) {
540 |   // 10+ lines of code
541 | }
542 | ```
543 | 
544 | ##### Good
545 | 
546 | ```js
547 | if (!car) {
548 |   return;
549 | }
550 | if (!black) {
551 |   return;
552 | }
553 | if (!turbine) {
554 |   return;
555 | }
556 | return 'batman!';
557 | ```
558 | 
559 | ```js
560 | if (!condition) {
561 |   return;
562 | }
563 | // 10+ lines of code
564 | ```
565 | 
566 | ## Prototypes
567 | 
568 | Hacking native prototypes should be avoided at all costs, use a method instead. If you must extend the functionality in a native type, try using something like [poser][23] instead.
569 | 
570 | ##### Bad
571 | 
572 | ```js
573 | String.prototype.half = function () {
574 |   return this.substr(0, this.length / 2);
575 | };
576 | ```
577 | 
578 | ##### Good
579 | 
580 | ```js
581 | function half (text) {
582 |   return text.substr(0, text.length / 2);
583 | }
584 | ```
585 | 
586 | **Avoid prototypical inheritance models** unless you have a very good _performance reason_ to justify yourself.
587 | 
588 | - Prototypical inheritance boosts puts need for `this` through the roof
589 | - It's way more verbose than using plain objects
590 | - It causes headaches when creating `new` objects
591 | - Needs a closure to hide valuable private state of instances
592 | - Just use plain objects instead
593 | 
594 | ## Object Literals
595 | 
596 | Instantiate using the egyptian notation `{}`. Use factories instead of constructors, here's a proposed pattern for you to implement objects in general.
597 | 
598 | ```js
599 | function util (options) {
600 |   // private methods and state go here
601 |   var foo;
602 | 
603 |   function add () {
604 |     return foo++;
605 |   }
606 | 
607 |   function reset () { // note that this method isn't publicly exposed
608 |     foo = options.start || 0;
609 |   }
610 | 
611 |   reset();
612 | 
613 |   return {
614 |     // public interface methods go here
615 |     uuid: add
616 |   };
617 | }
618 | ```
619 | 
620 | ## Array Literals
621 | 
622 | Instantiate using the square bracketed notation `[]`. If you have to declare a fixed-dimension array for performance reasons then it's fine to use the `new Array(length)` notation instead.
623 | 
624 | It's about time you master array manipulation! [Learn about the basics][24]. It's way easier than you might think.
625 | 
626 | - [`.forEach`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach)
627 | - [`.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice)
628 | - [`.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice)
629 | - [`.join`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join)
630 | - [`.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat)
631 | - [`.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift)
632 | - [`.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift)
633 | - [`.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push)
634 | - [`.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop)
635 | 
636 | Learn and abuse the functional collection manipulation methods. These are **so** worth the trouble.
637 | 
638 | - [`.filter`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/filter)
639 | - [`.map`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/map)
640 | - [`.reduce`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce)
641 | - [`.reduceRight`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/reduceRight)
642 | - [`.some`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/some)
643 | - [`.every`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/every)
644 | - [`.sort`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)
645 | - [`.reverse`](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse)
646 | 
647 | ## Regular Expressions
648 | 
649 | Keep regular expressions in variables, don't use them inline. This will vastly improve readability.
650 | 
651 | ##### Bad
652 | 
653 | ```js
654 | if (/\d+/.test(text)) {
655 |   console.log('so many numbers!');
656 | }
657 | ```
658 | 
659 | ##### Good
660 | 
661 | ```js
662 | var numeric = /\d+/;
663 | if (numeric.test(text)) {
664 |   console.log('so many numbers!');
665 | }
666 | ```
667 | 
668 | Also [learn how to write regular expressions][25], and what they actually do. Then you can also [visualize them online][26].
669 | 
670 | ## `console` statements
671 | 
672 | Preferably bake `console` statements into a service that can easily be disabled in production. Alternatively, don't ship any `console.log` printing statements to production distributions.
673 | 
674 | ## Comments
675 | 
676 | Comments **aren't meant to explain what** the code does. Good **code is supposed to be self-explanatory**. If you're thinking of writing a comment to explain what a piece of code does, chances are you need to change the code itself. The exception to that rule is explaining what a regular expression does. Good comments are supposed to **explain why** code does something that may not seem to have a clear-cut purpose.
677 | 
678 | ##### Bad
679 | 
680 | ```js
681 | // create the centered container
682 | var p = $('<p/>');
683 | p.center(div);
684 | p.text('foo');
685 | ```
686 | 
687 | ##### Good
688 | 
689 | ```js
690 | var container = $('<p/>');
691 | var contents = 'foo';
692 | container.center(parent);
693 | container.text(contents);
694 | megaphone.on('data', function (value) {
695 |   container.text(value); // the megaphone periodically emits updates for container
696 | });
697 | ```
698 | 
699 | ```js
700 | var numeric = /\d+/; // one or more digits somewhere in the string
701 | if (numeric.test(text)) {
702 |   console.log('so many numbers!');
703 | }
704 | ```
705 | 
706 | Commenting out entire blocks of code _should be avoided entirely_, that's why you have version control systems in place!
707 | 
708 | ## Variable Naming
709 | 
710 | Variables must have meaningful names so that you don't have to resort to commenting what a piece of functionality does. Instead, try to be expressive while succinct, and use meaningful variable names.
711 | 
712 | ##### Bad
713 | 
714 | ```js
715 | function a (x, y, z) {
716 |   return z * y / x;
717 | }
718 | a(4, 2, 6);
719 | // <- 3
720 | ```
721 | 
722 | ##### Good
723 | 
724 | ```js
725 | function ruleOfThree (had, got, have) {
726 |   return have * got / had;
727 | }
728 | ruleOfThree(4, 2, 6);
729 | // <- 3
730 | ```
731 | 
732 | ## Polyfills
733 | 
734 | Where possible use the native browser implementation and include [a polyfill that provides that behavior][27] for unsupported browsers. This makes the code easier to work with and less involved in hackery to make things just work.
735 | 
736 | If you can't patch a piece of functionality with a polyfill, then [wrap all uses of the patching code][28] in a globally available method that is accessible from everywhere in the application.
737 | 
738 | ## Everyday Tricks
739 | 
740 | Use `||` to define a default value. If the left-hand value is [falsy][29] then the right-hand value will be used. Be advised, that because of loose type comparison, inputs like `false`, `0`, `null` or `''` will be evaluated as falsy, and converted to default value. For strict type checking use `if (value === void 0) { value = defaultValue }`.
741 | 
742 | ```js
743 | function a (value) {
744 |   var defaultValue = 33;
745 |   var used = value || defaultValue;
746 | }
747 | ```
748 | 
749 | Use `.bind` to [partially-apply][30] functions.
750 | 
751 | ```js
752 | function sum (a, b) {
753 |   return a + b;
754 | }
755 | 
756 | var addSeven = sum.bind(null, 7);
757 | 
758 | addSeven(6);
759 | // <- 13
760 | ```
761 | 
762 | Use `Array.prototype.slice.call` to cast array-like objects to true arrays.
763 | 
764 | ```js
765 | var args = Array.prototype.slice.call(arguments);
766 | ```
767 | 
768 | Use [event emitters][31] on all the things!
769 | 
770 | ```js
771 | var emitter = contra.emitter();
772 | 
773 | body.addEventListener('click', function () {
774 |   emitter.emit('click', e.target);
775 | });
776 | 
777 | emitter.on('click', function (elem) {
778 |   console.log(elem);
779 | });
780 | 
781 | // simulate click
782 | emitter.emit('click', document.body);
783 | ```
784 | 
785 | Use `Function()` as a _"no-op"_.
786 | 
787 | ```js
788 | function (cb) {
789 |   setTimeout(cb || Function(), 2000);
790 | }
791 | ```
792 | 
793 | ## License
794 | 
795 | MIT
796 | 
797 | > Fork away!
798 | 
799 | # }
800 | 
801 | 
802 |   [1]: http://wiki.commonjs.org/wiki/CommonJS
803 |   [2]: http://requirejs.org/docs/whyamd.html
804 |   [3]: http://eviltrout.com/2014/05/03/getting-started-with-es6.html
805 |   [4]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions_and_function_scope/Strict_mode
806 |   [5]: http://editorconfig.org
807 |   [6]: http://dailyjs.com/2012/12/24/817-javascript-survey-results
808 |   [7]: http://blog.izs.me/post/2353458699/an-open-letter-to-javascript-leaders-regarding
809 |   [8]: https://github.com/jscs-dev/node-jscs
810 |   [9]: http://www.jslint.com/
811 |   [10]: https://github.com/jshint/jshint/
812 |   [11]: https://github.com/eslint/eslint
813 |   [12]: http://nodejs.org/api/util.html#util_util_format_format
814 |   [13]: https://github.com/jadejs/jade
815 |   [14]: https://www.imperialviolet.org/2014/02/22/applebug.html
816 |   [15]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators
817 |   [16]: https://github.com/jquery/jquery/blob/c869a1ef8a031342e817a2c063179a787ff57239/src/ajax.js#L117
818 |   [17]: http://stackoverflow.com/q/336859/389745
819 |   [18]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/function
820 |   [19]: https://github.com/buildfirst/buildfirst/tree/master/ch05/04_hoisting
821 |   [20]: http://ejohn.org/blog/partial-functions-in-javascript/
822 |   [21]: https://github.com/buildfirst/buildfirst/tree/master/ch05/04_hoisting
823 |   [22]: https://github.com/petkaantonov/bluebird/wiki/Optimization-killers#3-managing-arguments
824 |   [23]: https://github.com/bevacqua/poser
825 |   [24]: https://ponyfoo.com/articles/fun-with-native-arrays
826 |   [25]: https://ponyfoo.com/articles/learn-regular-expressions
827 |   [26]: http://www.regexper.com/#%2F%5Cd%2B%2F
828 |   [27]: https://remysharp.com/2010/10/08/what-is-a-polyfill
829 |   [28]: https://ponyfoo.com/articles/building-high-quality-front-end-modules
830 |   [29]: http://james.padolsey.com/javascript/truthy-falsey/
831 |   [30]: http://ejohn.org/blog/partial-functions-in-javascript/
832 |   [31]: https://github.com/bevacqua/contra#%CE%BBemitterthing-options
833 |   [32]: https://github.com/bevacqua/css
834 |   [33]: https://github.com/bevacqua/js/issues
835 | 


--------------------------------------------------------------------------------