Ever been in a situation where you’re under a lot of pressure or chasing a deadline, so you thought, “I probably shouldn’t bother with thoughtful variable names or documentation right now. I’ll clean it up later.”
But you never did. One compromise becomes two, then five, and before you know it, your codebase is full of little shortcuts, vague functions and variable names that make no sense.
When you come back months later, even you can’t quite remember what that function was supposed to do. Everything is a mess, and you end up spending hours figuring out what your code even does.
We’ve all been there.
Some months ago, I thought I found a solution with JSDoc and spent some time reading a bit about it. I found it really interesting, and so naturally I decided to use JSDoc comments in all of my next projects.
JSDoc is an API documentation generator for JavaScript. It is based on a series of tags (words preceded by the @ symbol) that are used before each function or module and describe the different characteristics of the code.
But then I hit a wall. Writing the comments was one thing; actually seeing them as useful documentation was another. The standard JSDoc output felt too impractical, and I found myself rarely checking the generated docs even on my own projects.
So I built JSDocViewer. It’s a small CLI tool that can be used to generate interactive documentation for your JavaScript projects using the JSDoc format.
Building JSDocViewer
JSDocViewer started as a simple Node.js CLI. The idea was to take a folder of .js files with proper JSDoc comments, parse them with the JSDoc tool and then serve the generated documentation in a local browser.
But I wanted a bit more than the standard output. I wanted something that could really be navigated through. Grouped and styled output. A clean single-page viewer. Easy integration into any project folder.
It’s open-source and available on my GitHub. The README has all the technical details.
But here’s some value I found while building that I want to share:
Consistently adding JSDoc comments helps you communicate about your code. Even the task of having to figure out the comment you will write on top of one method will prompt you to think and to clarify your method’s purpose
But Isn’t JSDoc a Bit… Old School?
Sure, there are flashier tools. But that’s kind of the point. JSDoc is low overhead. No need for new frameworks or build tools. Just write good comments and run the generator.
Want something fancier? Pair JSDoc with themes like DocStrap or use tools like TypeDoc for TypeScript.
But even plain JSDoc can transform any project’s readability especially for team projects, open-source contributions or onboarding new engineers.
Final Thoughts
Building JSDocViewer was a fun and clearly rewarding experience that showed the importance of clear communication in coding. As I developed the tool, I realized how effective JSDoc comments can be in making code more accessible and understandable.
So, if your codebase is filled with confusing functions and unclear outputs, try adding just a few JSDoc comments. Then run a tool like mine and see what your code actually looks like to someone new.
Your future self will thank you. And so will your teammates.
Want to try JSDocViewer? Check it out on GitHub. Got questions, ideas or comments on this? I’d love to hear from you.
Top comments (0)