Improve Your Javascript Codebase With Low Friction Typing Annotations

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.

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 that the types in JSDoc could also use Typescript declaration files!

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, 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!

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

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!