Use ‘eslint-annotated-reset’ to introduce linting to your legacy project

Introducing linting to a badly maintained legacy project can be a traumatic experience but the stress can be drastically reduced by careful use of ESLint and eslint-annotated-reset.

You’ve finally got agreement – you’re going to introduce linting of your Javascript code to your project, a project that’s desperately in need some TLC. Naturally, after careful evaluation, your linter of choice is ESLint, but when you run it against your code base you’re overwhelmed by the number of errors:

627 errors? When are you going to get time to fix those?
627 errors? When are you going to get time to fix those?

In the image above, taken from a real-life project that shall remain nameless to protect the guilty, we can see an all-too-common result of simply applying ESLint with the default settings; legacy code that generates hundreds, sometimes even thousands, of errors per file.

Of course, you want to resolve those problems. You want clean, consistent and maintainable Javascript. That’s why you’re introducing ESLint in the first place. But… you also want to meet your deadlines and they don’t necessarily allow for a massive refactoring of your code. Neither do you want to alienate your team, some of whom may already be hostile to linting and eager for opportunities to derail its introduction.

It was for exactly this situation that I created eslint-annotated-reset. This is simply an ESLint configuration file – .eslintrc – that you download from GitHub and drop into the root folder of your project. The next time you lint your code you’ll notice a drastic change; zero errors or warnings. The reason for this is simple, all of the linting rules have been turned off!

the easiest way to eat an elephant is one bite at a time

Why would you run ESLint will all of the rules turned off? eslint-annotated-reset is based on the principle that “the easiest way to eat an elephant is one bite at a time”. You may not have time to resolve 600 errors today but you might be able to resolve 6 or maybe even 60. After turning off all of the rules by dropping the .eslintrc file from eslint-annotated-reset into your project you can then selectively and methodically turn the rules back on, one at a time.

To turn a rule on, simply:

  • edit the .eslintrc
  • locate the rule you want to implement
  • change the setting from 0 (off) to 1 (throw a warning) or 2 (throw an error)

Let’s say we want to fix some of those 627 problems we saw earlier. Let’s start by making sure that all equality tests use “===” or “!==” rather than “==” and “!=”. That’s considered a best practice and can help prevent pernicious  bugs.

After opening .eslintrc  we locate the rule, in this case called “eqeqeq” (you can find these names in the console output from ESLint). There it is on line 63. We can confirm from the description that it’s the rule we want (that inline description is where the “annotated” in the name comes from).

"default-case": 0,     // require default case in switch statements
"dot-notation": 0,     // encourages use of dot notation whenever possible ***
"eqeqeq": 0,           // require the use of === and !== ***
"guard-for-in": 0,     // make sure for-in loops have an if statement
"no-alert": 0,         // disallow the use of alert, confirm, and prompt

A simple change to turn the rule on:

"default-case": 0,     // require default case in switch statements</pre>
"dot-notation": 0,     // encourages use of dot notation whenever possible ***
"eqeqeq": 2,           // require the use of === and !== ***
"guard-for-in": 0,     // make sure for-in loops have an if statement
"no-alert": 0,         // disallow the use of alert, confirm, and prompt

and we can rerun ESLint:

A much more manageable 26 errors
A much more manageable 26 errors

The eqeqeq rule is now the only one turned on and we have a much more manageable 26 errors. We can make and commit those changes and take a further bite of our elephant another day.

When you’re updating .eslintrc bear in mind that some rules take optional parameters in addition to the 0, 1 or 2. In eslint-annotated-reset these are indicated by three asterisks at the end of the description. You can find more details of the allowed options on the ESLint web site at:

http://eslint.org/docs/rules/rule-name-here

For example, the documentation for the ‘eqeqeq’ rule can be found at:

http://eslint.org/docs/rules/eqeqeq

Details of the eqeqeq rule from the ESLint website
Details of the eqeqeq rule from the ESLint website



The current (first) release of eslint-annotated-reset includes all rules included in version 0.20.0 of ESLint, released on 24th April, 2015. For convenience, the rules in .eslintrc are organised in the same way as they appear in the documentation pages of the ESLint website. As new rules are added to ESLint, eslint-annotated-reset will be updated to ensure they are always in sync.

ESLint allows you to choose which rules and stylistic conventions you want to apply to your Javascript code. With eslint-annotated-reset you can apply them at your own pace.


More:

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s