Skip to content

Commit

Permalink
[WiP] tidying up the readme see: #263
Browse files Browse the repository at this point in the history
  • Loading branch information
@nelsonic
nelsonic committed Nov 17, 2016
1 parent 8d16fd3 commit 3d3fff1
Showing 1 changed file with 96 additions and 52 deletions.
148 changes: 96 additions & 52 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,73 +1,103 @@
# goodparts [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/good-parts/issues) [![Travis](https://img.shields.io/travis/dwyl/goodparts.svg?maxAge=2592000)](https://travis-ci.org/dwyl/goodparts)
# `goodparts`

An ESLint Plugin that _only_ allows **JavaScript the _Good_ Parts** <br />
(_and "**Better Parts**"_) in your code so you can _ship_ more reliable code.

[![Travis](https://img.shields.io/travis/dwyl/goodparts.svg?maxAge=2592000)](https://travis-ci.org/dwyl/goodparts)
[![dependencies Status](https://david-dm.org/dwyl/goodparts/status.svg)](https://david-dm.org/dwyl/goodparts)
[![devDependencies Status](https://david-dm.org/dwyl/goodparts/dev-status.svg)](https://david-dm.org/dwyl/goodparts?type=dev)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/good-parts/issues)

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 <br />
how to write 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**, <br />
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. <br />
**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***<sup>TM</sup>.

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 <br >
only contains the _subset_ of JavaScript known as "**The _Good_ Parts**". <br />
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_, <br />
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? <br />
of JavaScript "**The _Good_ Parts**"
see: https://github.com/dwyl/goodparts/#videos

<!-- do we need this?
### *What is ESLint?*
ESLint is a Linting tool started by Nicholas C. Zakas,
it has become the _defacto_ linter in the JS community. see:
http://eslint.org/docs/about/

-->

## *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`:
```
{
"lint": "node_modules/.bin/goodparts path/to/files/for/linting"
}
```
> Example: ...
Now when you run the command:

```sh
npm run lint
```
You should _either_ see

or you should see

<br />

Expand All @@ -87,7 +117,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",
Expand All @@ -100,7 +135,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;
Expand Down Expand Up @@ -212,38 +248,47 @@ https://www.nngroup.com/articles/legibility-readability-comprehension/

<br />


### _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 piers
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!*)
> Simply that there is an *easy* way to ensure that your code will work
*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**,
<!-- its clear they are just trying to *look* smart to their piers
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 (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*"
Expand Down Expand Up @@ -275,7 +320,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.
Expand Down Expand Up @@ -303,7 +348,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/

<!-- Is this relevant...?
### Wikipedia as a *Representative* Sample of all Web Traffic
If you want a *representative* sample of all internet users,
Expand All @@ -318,11 +366,7 @@ and does its data-collection server-side (*so users without JavaScript
| Internet Explorer 9 | 1.28% |
| Total Legacy IE | 4.24% |

> See:
> https://stats.wikimedia.org/wikimedia/squids/SquidReportClients.htm
> https://analytics.wikimedia.org/dashboards/browsers/#all-sites-by-browser

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/
-->

0 comments on commit 3d3fff1

Please sign in to comment.