JavaScript Code Readability

Using a JavaScript library versus building the functionality yourself

Matt Zeunert — Mon, 02 Jul 2018 16:28:20 GMT

Libraries save time by letting developers reuse existing work done by others. Especially for languages like JavaScript, that come with a small standard library, external libraries are essential for building for large applications.

However there are some downsides as well, like unnecessary code and less control over the behavior of the third-party component.

This post will list the pros and cons of using a library instead of creating a custom solution.

Pros

Saving effort

This is the big one. Building functionality takes time, so if someone else already built it just re-using the code makes perfect sense.

Say you need a color picker for your app. You could spend 2 weeks building a custom tool, or you could spend an hour finding a library and learning how to use it. If the color picker isn't absolutely core to the experience of your app then you'll be way better of using an existing one.

Increasing quality

Not only will using a library be quicker than building it yourself, the end result will probably also be higher quality. The combined efforts of many people exceed the resources available in most cost-conscious companies.

People will already have found and fixed iOS-specific bugs, or discovered a UX problem. If you write the code yourself all the QA work is left for your team to do.

New team members may already be familiar with the library

If you use a popular library like Lodash or Redux your new team members may already have used it at a previous job and know the library API and best practices for using it.

When you move to a new project or company you can take your library knowledge with you and be more efficient from the get-go.

Better documentation

Unlike internal modules libraries are usually well documented (or at least have some documentation!). You can search through issues people had with the library in the past and find answers on StackOverflow.

Cons

Libraries may be hard to customize and debug

The library you're considering may only be 90% the way you want it and require several tweaks before you can use it. To adjust the library you need to understand the source code, including all the complexity the library was written to handle - even though the complexity wouldn't be needed just for your app!

Reading the code, understanding the build system, and making the adjustments takes a lot of effort! Sometimes writing just the code you need for your use case can be more effective.

Similarly, if you find a bug introduced by a third-party library tracking it down and fixing it can be difficult.

Download size

If you're writing front-end code every user will have to download the libraries used by your page. Since libraries are meant to be used in a wide variety of projects they will contain a lot of functionality and options that you don't actually need.

However some libraries allow you to limit what you include in your bundle to just what you need. For example, if you write import { filter } from "lodash" instead of import _ from "lodash" then tree shaking at build time removes all code that's not necessary.

Sometimes you can get the work done by just copying a few lines from Stack Overflow and putting it in a utils.js file.

Abstraction mismatch

Sometimes libraries can force you to solve a problem in a specific way, which may not be the most obvious for your use case. In that case it can be useful to wrap the library usage and provide a more useful API that's optimized for your needs to the rest of the application.

This especially applies if you are trying to standardize a bunch of existing solutions across your codebase. Building your own interface can make this a lot simpler.

Licensing issues

While open-source libraries are usually fine to use just because you can download the library for free doesn't mean you can use it commercially.

If you pay for a library there might still be restrictions, for example on how many different domains you can use it.

This might not be a decision you can make directly in the development team and can take a manager's time.

Security

When using external code there's a chance the dependency has security problems. Or a dependency of the dependency has security problems. Or that a version update introduces a security problem.

You can carefully review the library code, or use only libraries by large reliable vendors.

However, you have the greatest control when writing the code yourself. Of course you'll still have to write secure code, but at least the risk of having code that's intended to be insecure is greatly reduced.

Summary

Using lots of libraries is the norm for JavaScript projects. This saves time and creates a shared standard between projects.

When making a decision here are a few questions to consider:

How important is this functionality for your application?
How close is the library to what you need?
How accessible is the source code if you ever need to modify it?
Is the library well tested?
What libraries does your team have experience with?
How large are the resources of your project?

Automated code formatting with Prettier

Matt Zeunert — Thu, 10 May 2018 14:16:36 GMT

Prettier is a tool that automatically makes your code more readable and consistent with your project's style guide.

Prettier integrates with your editor, so your code is tidied up every time you save your changes:

Let's look at two examples:

function sayHi(name){  
    return 'Result: ' + name
}

Prettier will rewrite this as follows.

function sayHi(name) {  
  return "Result: " + name;
}

Here are the changes Prettier made:

Use " instead of '
Add an extra space before the function body (after the parameter list)
Add a semicolon at the end of the return statement

I'm using the default configuration here, but you can configure Prettier to prefer single quotes and no semicolons instead.

Another example. We've got a function with a lot of options. (If you've not seen it before, this code uses the ES6 object destructuring syntax).

function init({ option1, option2, option3, option4, option5, option6, option7 }) {  
  //...
}

But this is slowly becoming difficult to read. Prettier can fix the problem:

function init({  
  option1,
  option2,
  option3,
  option4,
  option5,
  option6,
  option7
}) {
  //...
}

No need to move the cursor and press enter 8 times! And if you realize you don't need option7 after all Prettier will instantly revert to the single line format.

Benefits

Prettier has had a surprisingly big impact on my productivity and happiness! I miss it every time I work on a project that's not set up with it.

Here's why Prettier is awesome:

No effort spent fixing formatting
No need to look up rules in a style guide
No time wasted discussing style in pull requests
When the style guide changes (or when it is first introduced) Prettier can automatically apply it across the whole code base.
Code copied from another project or from StackOverflow automatically adjusts

Setup with Visual Studio Code

There are Prettier plugins for many different editors available. Here I'll show the setup in Visual Studio Code.

1. Install the Prettier VS Code plugin

Open the Command Palette (under the View submenu, or using Cmd+Shift+P on Mac and Ctrl+Shift+P on Windows). Then select "Extensions: Install Extensions".

Search for "Prettier", click "Install", and then "Reload" once the installation is complete.

2. Run Prettier on a file

Now, if you open a JavaScript file and select "Format Document" in the Command Palette Prettier will tidy up your code!

3. Automatically run Prettier when saving a file

Open your workspace settings through the Command Palette. Then enable formatOnSave:

{
  "folders": [],
  "settings": {},
  "editor.formatOnSave": true,
}

Save your settings and now your code should be formatted every time a file is updated!

Prettier also supports languages other than JavaScript, e.g. TypeScript, HTML, CSS, or JSON. However, if you don't want those to be formatted you can control the formatOnSave setting by file type:

{
  "folders": [],
  "settings": {},
  "[javascript]": {
    "editor.formatOnSave": true
  }
}

Formatting existing code with command line

You can format the code for your entire project using the Prettier command line interface (CLI). First install the CLI tool:

npm install prettier --global

Then update your current code:

prettier "*/.ts" --write

Done! One quick warning though: automatically updating your code formatting means you'll make a big commit in source control where a large number of files are updated. That can make it harder to use e.g. git blame, since half the lines in a file may have last been modified in the Prettier commit.

Preventing callbacks from accidentally being called twice

Matt Zeunert — Sun, 22 Jan 2017 06:50:05 GMT

Asynchronous calls like this are extremely common in JavaScript:

fetchFile("example.js", function(fileContents){
    console.log(fileContents)
})

In order to avoid freezing the user interface while the file is loading, fetchFile returns immediately and then when example.js has been loaded the callback is called with the file contents.

Here's how fetchFile could be implemented:

function fetchFile(url, callback){
    // Using Fetch API because it's easy, but you could
    // also make a normal Ajax request
    fetch(url)
    .then(r => r.text())
    .then(function(text){
        callback(text)
   })
}

Let's add some caching, so if we request example.js twice, only one actual network request is made.

var cache = {}
function fetchFile(url, callback){
    if (cache[url]){
        callback(cache[url])
    }

    fetch(url)
    .then(r => r.text())
    .then(function(text){
        cache[url] = text
        callback(text)
   })
}

Done!

Actually, there's a problem with our code. Can you spot it?

...

When we run the example above, and the url is cached, the callback is actually called twice!

It's easy to think of calling the callback as a kind of asynchronous return statement. But execution continues after it, and the HTTP request to fetch example.js happens as if the file wasn't in the cache.

The fix is simple, make sure we return after calling the callback with the cached value:

    if (cache[url]){
        callback(cache[url])
        return
    }

But what can we do to prevent this mistake in the first place? There are two approaches.

Use an else branch even if it's not necessary

We could have avoided the whole problem if we had explicitly put the code that makes the HTTP request into an else branch:

function fetchFile(url, callback){
    if (cache[url]){
        callback(cache[url])
        return
    } else {      
        fetch(url)
        .then(r => r.text())
        .then(function(text){
            cache[url] = text
            callback(text)
       })
    }
}

Now the return statement isn't necessary any more and forgetting to put it in has no negative consequences.

Is there anything wrong with having both the else branch and the return statement? I don't think so. The return statement may be redundant and unnecessary, but it doesn't do any harm.

Wrap the callback so calling it twice throws an error

Another option is to keep track of whether the callback has already been called and throw an error if there's an attempt to call it again.

Checking whether the callback has been called before can be done with an onlyAllowOneCall method:

function fetchFile(url, callback){
      callback = onlyAllowOneCall(callback)

      if (cache[url]){
          callback(cache[url])
      }

      // Fetch logic goes here
}

function onlyAllowOneCall(fn){
     var hasBeenCalled = false;    
     return function(){
          if (hasBeenCalled){
               throw Error("Attempted to call callback twice")
          }
          hasBeenCalled = true;
          return fn.apply(this, arguments)
     }
}

If the function has been called before we'll throw an error, otherwise we call the original function fn.

fn.apply(this, arguments) ensures that our callback is called with the same this value and arguments as the original callback, so onlyAllowOneCall doesn't change the behavior of the callback.

This solution is a bit different from the first one, because it only surfaces the problem rather than fixing it.

We could just ignore any further callback calls after the first one. But then, even if the url is in the cache, the unnecessary HTTP request would still be made.

So, while the functionality of our app won't be affected, ignoring additional calls would hide the cost of unnecessary network requests.

Documenting build commands with NPM scripts

Matt Zeunert — Tue, 20 Dec 2016 09:36:00 GMT

In the past, running JavaScript followed a simple model. You wrote some code in file.js and then used a