diff --git a/README.md b/README.md
index a533318..440e45c 100644
--- a/README.md
+++ b/README.md
@@ -1,82 +1,147 @@
-# goodparts [](https://github.com/dwyl/good-parts/issues) [](https://travis-ci.org/dwyl/goodparts)
+# `goodparts`
+
+An ESLint Plugin that _only_ allows **JavaScript the _Good_ Parts**
+(_and "**Better Parts**"_) in your code so you can _ship more **reliable code**_.
+
+[](https://travis-ci.org/dwyl/goodparts)
[](https://david-dm.org/dwyl/goodparts)
[](https://david-dm.org/dwyl/goodparts?type=dev)
+[](https://github.com/dwyl/good-parts/issues)
+[](https://github.com/dwyl/goodparts "JavaScript The Good Parts")
+
-An ESLint Style that _only_ allows JavaScript the ***Good Parts*** (*and "Better Parts"*) in your code you can sleep at night.
## *Why?*
-Because this is the _best_ way we know how to write consistent,
-predictable and error free JavaScript code.
+Using JavaScript "**The _Good_ Parts**" (_abreviated to **`"goodparts"`**_)
+is the _best_ way we know
+how to write _simple_, _consistent_,
+_predictable_ and 100% cross-browser-compatible JavaScript code.
-Our ***guiding principal*** is:
+The ***guiding principal*** of `goodparts` is:
> "***perfection*** *is* ***attained*** *not when there is nothing more to add,
> but when there is* ***nothing more to remove***" ~
[Antoine de Saint-Exupéry](http://en.wikiquote.org/wiki/Antoine_de_Saint_Exup%C3%A9ry#Quotes)
-we subscribe to the "_code is for **humans** to read_" idea:
+We _agree_ that "_code is for **humans** to read_":
-> "_**Programs must be written for people to read**, and only incidentally for machines to execute._" ~ Harold Abelson
+> "_**Programs must be written for people to read**,
+and only incidentally for machines to execute._" ~ Harold Abelson
-> "_Any fool can write code that a computer can understand.
+> "_Any fool can write code that a computer can understand.
**Good programmers write code** that **humans** can
**understand**._" ~ Martin Fowler
-Also, we agree with:
-
-> "_**constraints** can actually **boost creativity**_". [Martin Villeneuve](https://www.ted.com/talks/martin_villeneuve_how_i_made_an_impossible_film)
-
The 3 biggest advantages of using `goodparts` in your code:
1. [***Readability***](https://en.wikipedia.org/wiki/Readability) - using _fewer_ ECMAScript (JS) language features means
people reading your code can get to the heart of what it *does*
rather than waste time trying to understand
how its been written.
-2. [***Shoshin***](https://en.wikipedia.org/wiki/Shoshin) - using _fewer_ JS features
-also means a _complete_ beginner has _less_ to learn before
-they _understand_ your code. This is _essential_ in Open Source
-if you want to make something that _anyone_ can use/modify/extend.
-3. [***Portability***](https://en.wikipedia.org/wiki/Software_portability) -
+2. [***Portability***](https://en.wikipedia.org/wiki/Software_portability) -
"Old" Browsers/Devices are a _fact_, even if it's "*only a small percentage*"
of people, we _chose_ to
[*empathize*](http://www.merriam-webster.com/dictionary/empathize)
with them by writing code that ***Works Everywhere***TM.
-
+3. ***Beginner-friendlyness*** or [***Shoshin***](https://en.wikipedia.org/wiki/Shoshin) - using _fewer_ JS features
+also means a _complete_ beginner has _less_ to learn before
+they _understand_ your code. This is _essential_ in Open Source
+if you want to make something that _anyone_ can use/modify/extend.
## *What?*
-A one-line install that will ensure your project's code works everywhere.
-(_or your money back!_)
+`goodparts` is a "[linter](https://en.wikipedia.org/wiki/Lint_%28software%29)"
+that _ensures_ your project's JavaScript code
+only contains the _subset_ of JavaScript known as "**The _Good_ Parts**".
+This _**guarantees**_ that
+your code ***works everywhere***. (_or your money back!_)
+
+
+### What _are_ "**The _Good_ Parts**"
+> If you are _unfamiliar_ with JavaScript "**The _Good_ Parts**"
+or need a _refresher_,
+please see @iteles' notes: [github.com/iteles/Javascript-the-**_Good_**-**Parts**-_**notes**_](https://github.com/iteles/Javascript-the-Good-Parts-notes)
+There are _several_ videos where Douglas Crockford covers
+the Why? What? and How?
+of JavaScript "**The _Good_ Parts**"
+see: https://github.com/dwyl/goodparts/#videos
+
+
## *How?*
-Simply install our configuration
+
+First _install_ the [**NPM Package**](https://www.npmjs.com/package/goodparts)
+in your Node.js/JS project:
```
-$ npm i --save-dev goodparts
+$ npm install goodparts --save-dev
```
-Then you can add the following script to your `package.json`:
+
+Then add the following script to your `package.json`:
+
```json
{
"lint": "node_modules/.bin/goodparts path/to/files/for/linting"
}
```
-The `goodparts` command line tool supports `eslint`'s autofix flag `--fix`. Not all errors can be autofixed, but a great deal can, simply with:
+> Example: [hapi-auth-jwt2/**package.json**#L68](https://github.com/dwyl/hapi-auth-jwt2/blob/5e09733c71c679633de42baa22cef615cdc81859/package.json#L68)
+
+Now when you run the command:
+
+```sh
+npm run lint
+```
+You should _either_ see **no output** if there are **no linting issues** in the code:
+
+
+
+***or*** if there are **linting issues** in the code you should see:
+
+
+
+
+### Autofix
+
+The `goodparts` command line tool supports `eslint`'s autofix flag `--fix`.
+Not _all_ errors can be autofixed, but a great deal can, simply with:
+
```
$ node_modules/.bin/goodparts /path/to/dir --fix
```
-While we're working on an [atom plugin](https://github.com/dwyl/goodparts/issues/243), you can still use `goodparts` to lint your code in your editor using the `linter-eslint` plugin for atom. To do this, you need a `.eslintrc.js` file in your project that reflects the `goodparts` configuration. Luckily we have a command line option for this too! Simply run:
+Example: (_fixing the linting "errors" from the example above_)
+
+
+
+> Note: the `--fix` command only fixed the missing semicolon but did not
+delete the extra (_unused_) `auth` variable.
+
+
+### Text Editor Linting _Plugin_?
+
+> If this is a feature you _need_ please _tell_ us by "up-voting":
+[atom plugin feature request](https://github.com/dwyl/goodparts/issues/243)
+
+While we're working on an [atom plugin](https://github.com/dwyl/goodparts/issues/243),
+you can still use `goodparts` to lint your code in your editor using the
+`linter-eslint` plugin for atom. To do this, you need a `.eslintrc.js`
+file in your project that reflects the `goodparts` configuration.
+Luckily we have a command line option for this too!
+
+Simply run:
+
```
$ node_modules/.bin/goodparts /path/to/dir --link
```
-This will create a symlink to the goodparts configuration file at `/path/to/dir/.eslintrc.js`, which we reccommend you git-ignore for now.
+This will create a `symlink` to the goodparts configuration file
+at `/path/to/dir/.eslintrc.js`, which we recommend you add it to `.gitignore` _for now_.
**Pre Commit Hook**
@@ -91,6 +156,20 @@ Then, assuming you have added the `lint` script described above, add the followi
}
```
+## Repo Badge ? [](https://github.com/dwyl/goodparts "JavaScript The Good Parts")
+
+
+If you use `goodparts` to lint your code and want to let other people know,
+you can add this badge in your repo:
+
+```js
+[](https://github.com/dwyl/goodparts "JavaScript The Good Parts")
+
+```
+
+> If you want to know more about "Badges" see: https://github.com/dwyl/repo-badges
+
+
## See the discussion we've had on each issue [here](https://github.com/dwyl/goodparts/wiki/Rules-Contents-page)
@@ -109,7 +188,12 @@ file, so you need to specify your environment e.g:
## Why (_extended version_)
-### Why Should Anyone _Listen_ to Douglas Crockford?
+We _strongly_ agree with the following sentiment/quote:
+
+> "_**constraints** can actually **boost creativity**_". [Martin Villeneuve](https://www.ted.com/talks/martin_villeneuve_how_i_made_an_impossible_film)
+
+
+### _Why_ Should Anyone _Listen_ to `Douglas Crockford`?
There are *many* places you can go to learn JavaScript,
*unsurprisingly* they *all* claim to teach you the "right way",
@@ -122,7 +206,8 @@ learning is any good is by listening to their their peers
or failing that, "*gut feeling*", neither of which are
a *reliable* measure of _quality_.
-Crockford is the Master Yoda of JavaScript, he has truly mastered the craft.
+Crockford is the "[Yoda](https://youtu.be/7YkbgvRMpW0?t=55s)"
+of JavaScript, he has truly [_mastered_](https://en.wikipedia.org/wiki/Mastery_learning) the craft.
He is a member of "[**TC39**](http://tc39wiki.calculist.org/about/people/)"
(the ECMAScript Technical Committee) responsible for
setting the language _standard_ to be implemented by web browser makers;
@@ -234,31 +319,18 @@ https://www.nngroup.com/articles/legibility-readability-comprehension/
-
-### _Should_ We Use ECMAScript 2015 (*AKA "ES6"*)?
-
-When you see someone _trying_ to use ***all*** the
-***latest features*** of **ECMAScript 2015**,
-its clear they are just trying to *look* smart to their peers
-and have not stopped to think/ask:
-+ "_will this code **work everywhere**_?"
-+ "_did the **users** ask me to use this (new) language feature_?
-(_or is there an existing way of doing this reliably...?_)"
-+ "_if I'm just going to transpile this through babel or add a pollyfill
-(for cross-browser compatibility) which means users have to load more bytes of code
-in their browser, what is true the advantage_...?"
-
-
-### Why does this matter / should I care?
+### Why does this matter / should I _care_?
If you are lucky enough to be building an *internal* web app
(*e.g: an intranet or "internal tools") and you "*know*" that
-everyone in the company is using Chrome that's *awesome*,
-thank your lucky stars and enjoy using all the latest & greatest features!
+_**everyone**_ in the company/organisation is using **"_Latest Chrome_"**
+that's *awesome*,
+thank your _lucky stars_ and enjoy using all the latest & greatest features of
+**ES6**!
If, like us, you live in the "*real world*" and build applications/websites
-that need to be *accessible* by and work *consistently* on any device/browser,
-then using only the *goodparts* is a good idea.
+that need to be *accessible* by and work *consistently* on _any_ device/browser,
+then using only the ***`goodparts`*** is a good idea.
> We are ***not suggesting*** that you (*your team/company*) *should*
> (*explicitly*) ***support IE8*** running on Windows XP! (*heavens no!*)
@@ -266,6 +338,28 @@ then using only the *goodparts* is a good idea.
*everywhere* so you don't have to *think* about it.
+### ES2015?
+
+The 6th edition JavaScript, _officially_ known as "**ES6**" or **ECMAScript _2015_**, was finalized in June 2015.
+This update adds significant new syntax for writing complex applications, including classes and modules
+
+https://en.wikipedia.org/wiki/ECMAScript#6th_Edition_-_ECMAScript_2015
+
+#### _Should_ We Use ECMAScript 2015 (*AKA "ES6"*)?
+
+When you see someone _trying_ to use ***all*** the
+***latest features*** of **ECMAScript 2015**,
+
+think/ask:
++ "_will this code **work everywhere**_?"
++ "_did the **users** ask me to use this (new) language feature_?
+(_or is there an `existing` way of doing this reliably...?_)"
++ "_if I'm just going to "**transpile**" this through babel or add a pollyfill
+(for cross-browser compatibility) which means users have to load more bytes of code
+in their browser (so pages take longer to load), what is true the advantage_...?"
+
+
### But caniuse.com says ...
Caniuse.com is a *fantastic* website. The UI is brilliant and for "*informal*"
@@ -297,7 +391,7 @@ please don't take their usage tables as "*gospel*" because they are flawed.
## Browser Stats *Facts*
-Most of us live in a *technology bubble*, we take it for granted
+Most of us live in a *technology bubble*, we take it for _granted_
that we always have Wifi or 4G and assume that because many of our
friends/colleagues are using MacBook Pros or iPhone 6s that
*everyone* is in the same situation.
@@ -325,7 +419,10 @@ they cannot; which means we are *relying* on non-technical people to
and had a person ask "*what is a browser*?" you will know that
*might* take a while...
+If you want to dive a bit deeper into the methodology used by StatCounter see:
+http://www.zdnet.com/article/net-market-share-vs-statcounter-whose-online-measurements-can-you-trust/
+
diff --git a/package.json b/package.json
index 4e40709..17bf1cf 100644
--- a/package.json
+++ b/package.json
@@ -3,6 +3,15 @@
"description": "An ESLint Style that only allows JavaScript the Good Parts (and \"Better Parts\") in your codebase.",
"version": "1.2.0",
"main": ".eslintrc.js",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/dwyl/goodparts.git"
+ },
+ "license": "GPL-2.0",
+ "bugs": {
+ "url": "https://github.com/dwyl/goodparts/issues"
+ },
+ "homepage": "https://github.com/dwyl/goodparts#readme",
"scripts": {
"test": "tape test/index.js test/**/*.test.js",
"coverage": "istanbul cover tape test/index.js test/**/*.test.js",
@@ -17,12 +26,25 @@
"eslint": "^3.9.1",
"minimist": "^1.2.0"
},
+ "pre-commit": [
+ "lint",
+ "test"
+ ],
"bin": "./bin/cmd.js",
"contributors": [
- "nelsonic",
"eliascodes",
"jrans",
"shouston3",
- "SimonLab"
+ "SimonLab",
+ "JMurphyWeb",
+ "Jbarget",
+ "iteles",
+ "nelsonic"
+ ],
+ "keywords": [
+ "JavaScript The Good Parts",
+ "Good",
+ "Simple",
+ "Less is More"
]
}
diff --git a/rules/es6.js b/rules/es6.js
index b537872..627d5c4 100644
--- a/rules/es6.js
+++ b/rules/es6.js
@@ -28,6 +28,7 @@ module.exports = {
'prefer-spread': 'off',
'prefer-template': 'off',
'require-yield': 'off',
+ 'require-await': 'off', // https://github.com/dwyl/goodparts/issues/277
'rest-spread-spacing': 'off',
'sort-imports': 'off',
'symbol-description': 'off',
diff --git a/rules/stylistic_issues.js b/rules/stylistic_issues.js
index b041f41..466110d 100644
--- a/rules/stylistic_issues.js
+++ b/rules/stylistic_issues.js
@@ -9,6 +9,7 @@ module.exports = {
'comma-style': [2, 'last'], // https://github.com/dwyl/goodparts/issues/215
'comma-spacing': [2, { before: false, after: true }], // https://github.com/dwyl/goodparts/issues/214
'comma-dangle': [2, 'never'], // https://github.com/dwyl/goodparts/issues/213
+ 'capitalized-comments': 0, // https://github.com/dwyl/goodparts/issues/278
'computed-property-spacing': [2, 'never'], // https://github.com/dwyl/goodparts/issues/212
'consistent-this': 0, // https://github.com/dwyl/goodparts/issues/211
'eol-last': 2, // https://github.com/dwyl/goodparts/issues/210
diff --git a/test/fixtures/es6.js b/test/fixtures/es6.js
index ae9db4a..1d60da4 100644
--- a/test/fixtures/es6.js
+++ b/test/fixtures/es6.js
@@ -27,6 +27,7 @@ module.exports = {
'prefer-rest-params': null,
'prefer-spread': null,
'prefer-template': null,
+ 'require-await': null, // https://github.com/dwyl/goodparts/issues/277
'require-yield': null,
'rest-spread-spacing': null,
'sort-imports': null,
diff --git a/test/fixtures/require-await.fail.js b/test/fixtures/require-await.fail.js
new file mode 100644
index 0000000..c050947
--- /dev/null
+++ b/test/fixtures/require-await.fail.js
@@ -0,0 +1,7 @@
+async function foo() {
+ doSomething();
+}
+
+bar(async () => {
+ doSomething();
+});
diff --git a/test/fixtures/require-await.pass.js b/test/fixtures/require-await.pass.js
new file mode 100644
index 0000000..8b33c3b
--- /dev/null
+++ b/test/fixtures/require-await.pass.js
@@ -0,0 +1,18 @@
+async function foo() {
+ await doSomething();
+}
+
+bar(async () => {
+ await doSomething();
+});
+
+function foo() {
+ doSomething();
+}
+
+bar(() => {
+ doSomething();
+});
+
+// Allow empty functions.
+async function noop() {}
diff --git a/test/fixtures/stylistic_issues.js b/test/fixtures/stylistic_issues.js
index 82ff6a8..5103803 100644
--- a/test/fixtures/stylistic_issues.js
+++ b/test/fixtures/stylistic_issues.js
@@ -33,6 +33,7 @@ module.exports = {
pass: ['obj["foo"];']
},
'consistent-this': null,
+ 'capitalized-comments': null, // https://github.com/dwyl/goodparts/issues/278
'eol-last': {
fail: [read('eol.fail')],
pass: [read('eol.pass')]
diff --git a/test/index.js b/test/index.js
index f4cb228..9060306 100644
--- a/test/index.js
+++ b/test/index.js
@@ -26,8 +26,8 @@ function ruleNotConfigured (rule) {
}
test('Testing All Conifgurable Rules', function (t) {
- Object.keys(allRules).forEach(function (rule) {
- var fCases, pCases;
+ Object.keys(allRules).forEach(function check_rule (rule) {
+ var fail_cases, pass_cases;
if (ruleNotConfigured(rule)) {
t.fail(rule + ' not configured');
@@ -41,17 +41,17 @@ test('Testing All Conifgurable Rules', function (t) {
return;
}
- fCases = testObject[rule].fail;
- pCases = testObject[rule].pass;
+ fail_cases = testObject[rule].fail;
+ pass_cases = testObject[rule].pass;
- if (fCases) {
- fCases.forEach(function (text) {
+ if (fail_cases) {
+ fail_cases.forEach(function (text) {
t.notOk(passesRule(rule, text), rule + ' fails');
});
}
- if (pCases) {
- pCases.forEach(function (text) {
+ if (pass_cases) {
+ pass_cases.forEach(function (text) {
t.ok(passesRule(rule, text), rule + ' passes');
});
}