Today, I want to show you how to improve context sharing between developers on your team. I have been following this methodology recently and it has improved my speed at which I can understand what a function or component is doing. The secret tech is… JSDoc.

JSDoc is used to generate API documentation automatically for your app. But the neat part is, this is also picked up by your editor! So VS Code can you that the function you just imported to get the subscription type of an account is deprecated and you should use a different function to get that data!

So, what’s the big deal? Isn’t it just more work?

Even when using JSDoc, there is a onus on the developer to add appropriate comments. But this could be automated at a PR level using LLMs if needed. We should understand that overdoing JSDocs will get you nowhere in my opinion. Using it annotate a one liner of a function, marking it as deprecated, or attaching a tutorial to use a component will be some good use cases for it. I’m sure you can find more use cases. I’m gonna share a few ways on how I used it to improve my productivity and (hopefully) my team’s productivity!

Examples

Adding function descriptions

The functionality that I use the most. I usually add a one line description to functions that need them, so that me, or my team mates can get a quick understanding of what that function might do. I tend to avoid overdoing the description, like writing what the algorithm inside the function does in most cases. This just adds to the overhead and people will not bother to edit it unless it’s small enough.

You can annotate JS functions with a @description tag that shows up on hover.

/**
 * @description Collapsible component that hides and shows content
 */
export function Collapsible({
  children,
  title,
}: PropsWithChildren & { title: string }) {
  ....
}

@description example

Pro tip: JSDoc supports markdown inside VSCode! But if you’re using it as a standalone tool, please add the markdown plugin to add support for rendering markdown content.

Marking a function as deprecated

When I’m working on enhancements in existing features, I would need to move an API from V1 to V2. But often, there would be a beta phase where both the apis are needed, or the old apis are needed for legacy usecases, but we would use the new API’s from the feature launch. To alert other developers to use a new API, you can tag a function as @deprecated, so they can know that the function is not supposed to be used anymore.

@deprecated example

Tip: You can also add a {@link} to link other files or URLs so that people can find the alternate of a function or component.

Adding usage tutorials for a component / function

When I was working on a new Custom Tab bar component, I had to write a small example on how to use the component. So I added an example using the @example tag to let people know how to use it.

You can also added a @tutorial tag to link an article on how to use it.

@tutorial example

Adding TODOs?

There are alternate ways to acheive this functionality (like TODO Tree), but JSDoc also provides a way to add TODO’s, using the @todo keyword.

@todo example

Go read JSDoc documentation and maybe you can find some interesting tags that could be useful to your workflow as well!

Happy readings!

One Trick to Improve Readability of your Javascript Functions