diff --git a/README.md b/README.md index 93c446b..67d03c4 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,10 @@ This is fork from [jQuery Code Style] and follows the same licensing. This style guide should be applied to all ES6Rocks code to improve readability and consistency. +## Strict mode + +Always use strict mode. + ## Spacing - Indentation: 4 spaces, no tabs. @@ -16,10 +20,10 @@ This style guide should be applied to all ES6Rocks code to improve readability a ```js // Bad - if ( condition ) return; + if (condition) return; // Good - if ( condition ) { + if (condition) { return; } ``` @@ -109,18 +113,36 @@ html = '
The sum of ' + a + ' and ' + b + ' plus ' + c + ``` Lines should be broken into logical groups if it improves readability, such as splitting each expression of a ternary operator onto its own line even if both will fit on a single line. +If possible, use ternary conditions between parentheses to ensure the logic, for the reader. + +```js +var baz = (firstCondition( foo ) && secondCondition( bar )) ? + qux( foo, bar ) : + foo; +``` + +Never use multiple ternary conditions in the same instruction. ```js -var baz = firstCondition( foo ) && secondCondition( bar ) ? +// bad +var baz = (firstCondition( foo ) && secondCondition( bar )) ? + qux( foo, bar ) : + foo? 'abc': 'def'; + +// god +var baz = (firstCondition( foo ) && secondCondition( bar )) ? qux( foo, bar ) : foo; + +baz = baz? 'abc': 'def; + ``` When a conditional is too long to fit on one line, successive lines must be indented one extra level to distinguish them from the body. ```js -if ( firstCondition() && secondCondition() && - thirdCondition() ) { +if (firstCondition() && secondCondition() && + thirdCondition()) { doStuff(); } ``` @@ -172,14 +194,20 @@ Strict equality checks (`===`) must be used in favor of abstract equality checks undefOrNull == null; ``` +When checking for `undefined`, prefer using `void(0)` instead. + +```js +if (something === void(0)) { + // magic +} +``` + ## Comments Comments are always preceded by a blank line and must go over the line they refer to. There must be a single space between the comment token and the comment text. -Multi-line comments - also named block level comments - are only used for file and function headers. - ```js // We need an explicit "bar", because later in the code foo is checked. var foo = 'bar'; @@ -189,23 +217,120 @@ var foo = 'bar'; // line comment form. ``` +Multi-line comments - also named block level comments - are only used for file and function headers and should start with `/**`, end with `*/` and have a `*` for each comment line, like so: + +```js +/** + * This function does something. + * + * In this function, you will + * find magic! + */ +function doSomething() { + // magic +} +``` + +Annotation comments are also welcome. + +```js +/** + * This method does something. + * + * In this method, you will + * find magic! + * + * @method doSomething + * @param {String} someArg The spell + * @return void + */ +someObj.doSomething = function(someArg) { + // magic +} +``` + + ## Quotes Use single quotes: `'`. Strings that require inner quoting must use single outside and double inside. ## Semicolons -Use them. Never rely on ASI. +Use them. Never rely on ASI. EVER! ## Naming Conventions -Variable and function names should be full words, using camel case with a lowercase first letter. Names should be descriptive but not excessively so. Exceptions are allowed for iterators, such as the use of i to represent the index in a loop. +Variable and function names should be full words, using camel case with a lowercase first letter. +```js +let someData; + +function someFunc() {}; +``` -Constructors need a capital first letter, but modules do not. +Names should be descriptive but not excessively so. Exceptions are allowed for iterators, such as the use of i to represent the index in a loop. + +Constructors and classes need a capital first letter(pascal case), but modules do not. + +```js +function SomeConstructiveFunc() {} +class SomeClass {} +``` ## Switch statements The usage of switch statements is generally discouraged. +But you need to use it, besure you cast its type: + +```js +switch (parseInt(theNum, 10)) { + case 1: { break; } + case 2: + case 3: + case 4: { break; } + default: {} +} +``` +Also, always use braces, and prefer to define a default to it whenever possible. + +## Throwing, Trying and Catching + +- ALways throw an `Error` instance. + +```js +// bad +throw 'something went wrong!'; + +// god +throw new Error('something went wrong!'); +``` + +- Avoid using multiple try/catch. + +```js +// bad +try { + doThis(); + try { + andThenThat(); + } catch (e) { + console.error('that failed'); + } +} catch (e) { + console.error('this failed'); +} + +// good +try { + // in case of error, throws a new Error('this failed'); + doThis(); + // in case of error, throws a new Error('that failed'); + andThenThat(); +} catch (e) { + console.error(e.message); +} +``` + +Never leave a `catch` empty. ## Linting and checking