From cdbed03975ff67ac3a108bdbaca8b48ffa41b786 Mon Sep 17 00:00:00 2001 From: Felipe Nascimento de Moura Date: Thu, 21 May 2015 11:21:30 -0300 Subject: [PATCH 1/3] Some updates These are just some ideas. --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 133 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 93c446b..59f9a74 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. @@ -12,11 +16,11 @@ This style guide should be applied to all ES6Rocks code to improve readability a - Lines should be no longer than 100. There are 2 exceptions: - If the line contains a comment with a long URL. - If the line contains a regex literal. This prevents having to use the regex constructor which requires otherwise unnecessary string escaping. -- `if`/`else`/`for`/`while`/`try` always have braces and always go on multiple lines. +- `if`/`else`/`for`/`while`/`try` always have braces and always go on multiple lines, and always with one space before and after `(` and `)`. ```js // Bad - if ( condition ) return; + if(condition) return; // Good if ( condition ) { @@ -109,11 +113,29 @@ 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. @@ -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 is 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'); +} + +// god +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 From 464f9c6eb7011fc0888f948c4e7d5c28ab8f8cba Mon Sep 17 00:00:00 2001 From: Felipe Nascimento de Moura Date: Thu, 21 May 2015 11:27:23 -0300 Subject: [PATCH 2/3] [ * ] Fixed typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 59f9a74..210e88b 100644 --- a/README.md +++ b/README.md @@ -290,7 +290,7 @@ switch (parseInt(theNum, 10)) { default: {} } ``` -Also, always use braces, and prefer to define a default to it whenever is possible. +Also, always use braces, and prefer to define a default to it whenever possible. ## Throwing, Trying and Catching From 978539a77f234378ceacc515f2003ab87eae5f7f Mon Sep 17 00:00:00 2001 From: Felipe Nascimento de Moura Date: Thu, 21 May 2015 11:38:10 -0300 Subject: [PATCH 3/3] [ ^ ] Complying to Harmonic current format --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 210e88b..67d03c4 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,14 @@ Always use strict mode. - Lines should be no longer than 100. There are 2 exceptions: - If the line contains a comment with a long URL. - If the line contains a regex literal. This prevents having to use the regex constructor which requires otherwise unnecessary string escaping. -- `if`/`else`/`for`/`while`/`try` always have braces and always go on multiple lines, and always with one space before and after `(` and `)`. +- `if`/`else`/`for`/`while`/`try` always have braces and always go on multiple lines. ```js // Bad - if(condition) return; + if (condition) return; // Good - if ( condition ) { + if (condition) { return; } ``` @@ -141,8 +141,8 @@ 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(); } ``` @@ -197,7 +197,7 @@ undefOrNull == null; When checking for `undefined`, prefer using `void(0)` instead. ```js -if ( something === void(0) ) { +if (something === void(0)) { // magic } ``` @@ -298,10 +298,10 @@ Also, always use braces, and prefer to define a default to it whenever possible. ```js // bad -throw "something went wrong!"; +throw 'something went wrong!'; // god -throw new Error("something went wrong!"); +throw new Error('something went wrong!'); ``` - Avoid using multiple try/catch. @@ -319,7 +319,7 @@ try { console.error('this failed'); } -// god +// good try { // in case of error, throws a new Error('this failed'); doThis();