JSDocs: A Powerful Tool for Boosting Codebase Readability and Collaboration

When I made the full switch over to Typescript I thought I didn't need JSDocs anymore as arguments and return types are provided by Typescript and if you name your functions and arguments well then it's obvious what the code is doing. Right? WRONG!

One thing I have learnt over the years is even if your code seems obvious to you, it may well be not obvious to others who are also working on the same codebase. To code with empathy to other developers is crucial when working in a team. This is where I recently discovered JSDocs can really help especially when working within VSCode.

I don't know much about the origins of JSDocs but judging by the website they've been around for a while. JSDoc is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor. There are a couple of really cool things it does. You add documentation comments directly to your source code, right alongside the code itself. The JSDoc tool will scan your source code and generate an HTML documentation website for you. This is cool but what I prefer is what it does within VSCode.

Here we have a very simple function just to show the functionality that JSDocs can give you within VSCode.

/**
 * @function
 * @description Helper function to limit amount of decimal places to 4
 * for float numbers
 * @see https://jsdoc.app/about-getting-started.html
 */
export const handleDecimalPlaces = (value: number) => {
  return value.toFixed(4);
};

Each comment must start with a /** sequence in order to be recognised by the JSDoc parser. Special "JSDoc tags" notified by the '@' sign can be used to give more information. In the above '@function' and '@description' for example.

Now when you use this function in VSCode and hover over the function with your mouse you see this:

How cool is that?! This is so useful for other developers coming into your team or are new to your codebase as they can hover over functions within the code and find out what this function does and open any links you may provide to get further information.

I used to be of the opinion that the less comments the better. That your code should be readable enough that comments are not required. But over time I have learnt that when working on many codebases at once, having some helpful information and links in your code can really help other developers out and provide context for why the code is written in the way it is.

JSDocs is an old tool but still can be very useful in today's development cycle. A team that has empathy for each other and writes code that is readable and easy to use for other team members is a team that can develop quickly and efficiently. It's also a more pleasurable experience for each developer on that team. It does require a little extra effort when developing but the rewards, especially over the long run, far outweigh that additional effort.