Improve Your Javascript Codebase With Low Friction Typing Annotations
Tags: javascript, productivity, typescript
Published: 2020-04-01 02:24:02


For this trick, you will need VS Code as your IDE, and a mix of JSDoc/Typescript declaration file knowledge.

## Background
I was recently working on a very large React codebase made by developers who made their own framework inside the app to manage displaying of widgets and visualizations in a dashboard.

![Connect the dots](https://dev-to-uploads.s3.amazonaws.com/i/tkf9hwjiuj44c3ctti5h.jpg)

## The Problem
It was hard to follow the flow of data as it went against React's declarative style, and instead had a preference for configurations to define how the UI looked and worked.

This codebase was written for a fast moving start up, so of course, documentation was not a priority.

I wanted to make things easier for new people on boarding to reduce the amount of questions asked and file digging I had to do.

## The Solution
I already knew from previous experience that VS Code had support for JSDoc. I discovered [during my research](https://github.com/Microsoft/TypeScript/wiki/JavaScript-Language-Service-in-Visual-Studio#JsDoc) that the types in JSDoc could also use Typescript declaration files!

![JSdoc + typescript](https://raw.githubusercontent.com/wiki/Microsoft/TypeScript/images/decl1.png)

This was awesome news, I could define types for all these different utility functions in my own declaration files, so that I would at least get some intellisense to help me when navigating the code base.

I then had the idea of expanding on this idea some more, and wanted to try using typescript declaration files defined by open source libraries. This way I could leverage all the documentation defined by library authors and @types contributors around the world.

After some failed google searching, I found the answer in the typescript docs of all places. In this [reference](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#import-types), you can see the type being imported from a separate file of the project being used in the JSDoc. This got me thinking... could I import from a `node_module` ? Turns out, you can!

```js
  /*
   * @param {string} chartType 
   * @returns {import ("highcharts/highcharts").Options} Returns a highchart options object used for defining your highchart component.
   */
   const getChartOptions = (chartType) => {
     // Some logic here...
     return { ...chartObject }
   }
```

With this simple JSDoc, the return object of the `getChartOptions` will get intellisense which will show all the available properties and a brief description of what it does when you hit `ctrl+space`. This is super useful when navigating something like a charting library which has types with several dozen properties and tons of nesting.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/zdyea5aw09r3upptsr7j.png)

## Summary

With a few extra comments in your javascript codebase loaded into VS Code, you can leverage a ton of documentation in an easily accessible way for developers. 

No extra dependencies or vs code extensions were needed

Developers new to types can get a small taste of how much they help without having to fight a compiler.

Not having to open a browser to lookup API docs and staying in your IDE  should avoid distracting yourself with the 20 different tabs you have open in Chrome.

I hope this short post will boost your team productivity. Let me know what you think in the comments and let me know if there is anything I could add to this way of making a codebase more accessible!