JSDoc vs TypeScript #typescript

[csoto]

JSDoc can be really handy when working in big codebases with old code, particularly when it’s not feasible to refactor the code into TS. It’s been very handy for me in the past.

[hansiboy]

The nicest thing about js doc is that I can right-click and go to the code to see for myself how the library implemented the function

[TheKnocKY]

I think the key difference why people are switching is that jsdoc is opt-in typing. I can write a bunch of functions and only type the ones that actually interface with other code - say, only the ones that the library exports. Typescript is more like opt-out typing. You have to explicitly put any, or ts-ignore everywhere, otherwise the ts compiler starts infering static types on your code.

JsDoc allows you to do the "trust me bro, this function will return a number" while not actually forcing you to type internals.

[gobluebro]

My company refuses to upgrade to ts. Jsdoc has been one of the thing keeping me sane.

[juliohintze]

One thing that I love about JSDoc is that you can create your types in .ts files, and use them in a JS file with the import() function (like @type {import('./types').TheType}). So a lot of things that JSDoc lacks in typing can be circumvented by doing this.

[MrWholphin]

JSDoc does not require tsc for runtime, so it’s much faster to iterate on changes and simpler to deploy. Additionally, a well documented ts project will have JSDoc blocks everywhere, so the syntax ‘advantage’ isn’t that much

[kbsanders]

I use JSDoc comments in my TS code to document the function and parameters with descriptions but not the types of the parameters themselves.

[PieterWigboldus]

You dont need to build JS, only validate/lint, so no transformation is needed in the JS version.
The browser en Node.js dont understand TS, that is always transformed to JS, also with ts-node.
So JS with JSDoc is the best of both worlds.
Also JSDoc makes more clear that it is just documentation, not for runtime.
And you can use still import TS types and interfaces inside JSDoc.
Which version looks better is a personal preference.
And I think TS makes it less clear that the annotations are not validation, only helping with development.

[jonkoops]

I think this is a bit naive, as JSDoc has the advantage that you don't need to compile it, that alone makes it much easier to debug and integrate in tooling that is not Typescript native.

[MobiusCoin]

Okay, I gave it a whirl last night. Used the PokeAPI, JSDoc, Alpine, and Fast Average Color to build a simple app that sorts Pokemon by their color. Crucially no build step. AND... it was pretty rough. Hand annotating the API endpoints was a lot of work in itself. I really want no build JS to be viable but you quickly realize what makes TS great is its ecosystem.

[ClassicalByMetal]

I've had plenty of discussions around JSDocs in codebases, mostly where the consensus is to avoid them (comments like "code should be readable without explanation" get thrown around a lot), but I still think they are still really useful for contextualising more complex functionality. It's especially helpful for a11yship - they can be incredible for those with dyslexia, dyscalculia, ADHD etc., so I'll always advocate for them where appropriate.

[dvillegaspro]

JSDoc is more to write but also allows detailed explanations in your intellisense and it is opt-in unlike typescript. I try to use both because typescript provides type safety during running builds and JSdocs helps me document code better.

[sinasalahshour]

but you don't need the build step for running the thing

[thegrumpydeveloper]

Not sure the hate for the build some people have. You’re going to want to strip those comments and minify anyways just take a build step. Running from command line tsx, ts-node with swc and bun are all fast too. No reason to use jsdoc with worse syntax and worse type checking than normal ts

[mahadevovnl]

I prefer JSDoc next to TS. They help one another so much. I use JSDoc where I find human-readable comments to be useful, and I use it when declaring code examples and resources.

TypeScript will be done for things where you don't need those additions.

[hkupty]

JSDoc is like javadoc, KDoc (kotlin), luadoc and many others. As in those other cases, it can do one thing that types alone have a hard time doing: Communicating context and intent. It s is really not just to describe "what" - this is what types usually do, but "why". If you compare it with types, only from the "amount of code" dimension, you're narrowing the comparison and disregarding the other benefits of good documentation, which exist even in static typed languages.

[mattshnoop]

The point about needing a lot of lines to add the types is totally moot to me because most of my TypeScript functions are going to have doc comments for the parameter descriptions anyways…

[re.liable]

Love JSDoc. I just find a lot of things are hard to do there, e.g. generics, type aliases, type functions. And as you say, needing tsconfig to actually check the types (in VSCode at least).

It's really great when I can't use TS directly though. But I also just recently discovered Deno and `tsx` (the package/executable, not TypeScript JSX)

[garretmh]

I disagree with your takeaway on this which makes it sound like TS is just better. TS files require tooling and a build step. JSDoc is a progressive enhancement: it supports almost everything TS does but also always just works. Also the verbosity is nothing if you’re including JSDoc comments anyway.

I usually prefer to use TS for programs and JSDoc for libraries.

[skeleton_craftGaming]

Yes, but I don't have to compile my JavaScript using jsdoc