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.

Why?

Using JavaScript "The Good Parts" (abbreviated to "goodparts") is the best way we know
how to write simple, consistent, predictable and 100% cross-browser-compatible JavaScript code.

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

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

"Any fool can write code that a computer can understand.
Good programmers write code that humans can understand." ~ Martin Fowler

The 3 biggest advantages of using goodparts in your code:

1. 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. Portability - "Old" Browsers/Devices are a fact, even if it's "only a small percentage" of people, we chose to empathize with them by writing code that Works Everywhere^TM.
3. Beginner-friendlyness or 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?

goodparts is a "linter" 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

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?

First install the NPM Package in your Node.js/JS project:

$ npm install goodparts --save-dev

Then add the following script to your package.json:

{
  "lint": "node_modules/.bin/goodparts path/to/files/for/linting"
}

Example: hapi-auth-jwt2/package.json#L68

Now when you run the command:

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

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

While we're working on an atom plugin, 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 recommend you add it to .gitignore for now.

Pre Commit Hook

If you would like to add a pre-commit hook to check that your linting is up to scratch:

$ npm i -D pre-commit

Then, assuming you have added the lint script described above, add the following line to your package.json:

{
  "pre-commit": ["lint"]
}

Repo Badge ?

If you use goodparts to lint your code and want to let other people know, you can add this badge in your repo:

[![JavaScript Style Guide: Good Parts](https://img.shields.io/badge/code%20style-goodparts-brightgreen.svg?style=flat)](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

(Frequently Asked) Questions?

Q: If the intention is to use only the Good Parts, why not use JSLint and not bother with this tool?
A: the simple answer is JSLint (DC's tool), does not allow you to include a project-wide configuration file, so you need to specify your environment e.g: /*jslint node: true */ in every file, which gets old fast.

tl;dr

Why (extended version)

We strongly agree with the following sentiment/quote:

"constraints can actually boost creativity". Martin Villeneuve

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", and as a beginner it's virtually impossible to detect which is the "right" path because there is a lot of marketing hype which can easily be mistaken for "fact".

The only way a beginner can determine if the source of 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 "Yoda" of JavaScript, he has truly mastered the craft.
He is a member of "TC39" (the ECMAScript Technical Committee) responsible for setting the language standard to be implemented by web browser makers; to say that DC "knows" JavaScript inside-out is an understatement. He invented JavaScript Object Notation ("JSON") data format (the Standard for REST APIs) and wrote the first JSON parser. He painstakingly scoured the entire ECMAScript specification in order to compile his list of Good (and Bad) Parts, a subset of the language that can be trusted and used reliably anywhere. He has been lead engineer at Yahoo and Paypal and run his own web consulting company specialising in JS applications.

Most people will not look at http://javascript.crockford.com and think: "yes, this looks like the place to learn JavaScript..." and that's a shame because its "plainness" (lack of pictures or medium-style presentation) does not do justice to the insight he shares.

Better Parts

Selected Quotes Quotes

Highlights from Douglas Crockford's "Better Parts" Talk: https://youtu.be/bo36MrBfTk4
(first presented at JSConfUY 15th March 2014)

• "Programs must be perfect or they are not right." - 02:21

• "The Good Parts are what's left when you remove all the bad parts" - 02:30

• "Criteria for deciding if something is a good part or not is this: if a feature is sometimes useful and sometimes dangerous, and if there is a better option, always use the better option." - 02:41

• "this is maybe the most important idea tonight:
  We are not paid to use every feature of the language we are paid to write programs that work well and are free of error - 03:10

• "People don't like programs with errors in them and they wish we would stop doing that." 03:21

• "Sometimes we work against our own interest, in trying to demonstrate mastery over the language, but we are actually making things worse not better" - 03:29

• "This will save you some day, if you comply with it..." - 07:47

• "It's not just a matter of opinion, there is a good reason for everything that JSLint asks you to do"

• "I'm only telling you not to use the tools that are unnecessary and dangerous" - 07:50

• "Eventually, we want to be writing with one voice, we want all of the software we develop in a project to look as though it was developed by the same person, and that person is really smart" - k 08:39

• "Keystroking time is irrelevant, so if you're doing something stupid to shave keystrokes, that's counter-productive." - 09:17

• "There's a good reason those features were added to the language. I can tell you reliably, that is absolutely not true." - 09:55

• "Just because a 'foot gun' is in the language, doesn't mean you want to shoot your foot off" - 10:26

Videos

• JavaScript: The Good Parts (Google Tech Talks): https://youtu.be/hQVTIJBZook
• The Better Parts - JSConfUY 2014: https://youtu.be/bo36MrBfTk4
• Douglas Crockford Complete Playlist: https://www.youtube.com/playlist?list=PLEzQf147-uEpvTa1bHDNlxUL2klHUMHJu

Background Reading

• Comparison of JS Linting Tools: https://www.sitepoint.com/comparison-javascript-linting-tools/
• The Sorry Legacy of Internet Explorer: http://www.wired.com/2016/01/the-sorry-legacy-of-microsoft-internet-explorer/
• Readability: https://www.nngroup.com/articles/legibility-readability-comprehension/

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

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,

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" (i.e. non-scientific) discussions about which HTML5 features are available in a browser, we use it often! But caniuse.com bases it's pretty graphs on the data from statcounter.com which is good but has several flaws in data collection methodology:

1. Small sample size - StatCounter collects data for a
   "_network of more than 3 million websites" if you know anything about the internet you will realize that this is a drop in the ocean. 3M sites is less than 0.3% of websites on the internet¹.

2. Over counting - StatCounter counts all page views made by a given user (agent) which means that heavy users have higher representation in the sample. (If the website does not work on a given browser/device the person will obviously not get past the first page!) By contrast NetMarketShare only counts the first pageview which means it gives an equal weighting to each visitor.

¹According to netcraft.com there are over a billion (active) websites online in May 2016. It is unclear which websites StatCounter is sourcing its data from, 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 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.

At the time of writing Internet Explorer 8 still has a 5.95% (global) Market Share (according to netmarketshare.com April 2016)

Even if we think that "everyone" has switched to Chrome, the facts (stats) are clearly not supporting this hypothesis!

58% of people are still using an Operating System that is no longer supported by Microsoft (Windows 7 & XP market share = 58.45%) ... Microsoft ended "mainstream" support for Windows 7 on Jan 13 2015 so even if they want to force everyone to upgrade to "Edge", they cannot; which means we are relying on non-technical people to manually upgrade their browser... If you have ever been in Tech support 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/