DEV Community

loading...

Improve Your Javascript Codebase With Low Friction Typing Annotations

wichopy profile image Will C. Updated on ・3 min read

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

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!

JSdoc + typescript

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 }
   }
Enter fullscreen mode Exit fullscreen mode

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

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!

Discussion (0)

pic
Editor guide