I have recently taken an interest in TypeScript. Not just because it brings features that are considered essential to production-grade applications, but also because it makes using a code editor such as Atom or VS Code more useful for me.
However, I was not very keen on the idea of configuring the TypeScript compiler on every project I wanted just for type annotations and autocomplete suggestions. Code editors already have come a long way when it comes to suggestions, but I also wanted to incrementally adopt my own type definitions, thus removing my reliance on some very smart guesses by a code editor.
So, funnily enough, while going through some code behind IndieKit, a Micropub server I am using while building Celestial, I was intrigued by a very distinctive comment block just before some function definitions.
Here’s what it looks like:
/**
* @param {boolean} update - updates the logged in state
* @returns {boolean} - returns a success/error indicator
*/This wasn’t the first time I saw it in open source projects. However, it definitely was the first time I wanted to explore this. There is a sense of longevity in wanting to self document code without the additional burden and build step of a compiler. Or leaving comments everywhere with no sense of organization to it.
This comment block comes from JSDoc. An intended use-case is generating an HTML document based on all your JSDoc definitions. Make freshly hired developers happy! 😊
VS Code offers built-in integration. Typing /** will lead it to suggest a JSDoc block. Hit enter and you’re on your way. Type @ and you get a bunch of tag suggestions. It understands most of JSDoc, though I have come across instances where it fell short from the documentation.
Okay, so your project has grown a bit. Quite a bit. It’s time to use TypeScript but your code is now unhappily littered with JSDoc. Worry not; VS Code offers you an option to infer type annotations from JSDoc and fill them in for you. So cool, right?
I’ll leave you to explore it, possibly learn and start using it. It does circumvent the TypeScript tax for simple projects — perhaps even mid-size projects.