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.
That's a TS feature. It's only possible in JSDoc because the tsserver in your IDE/editor can use the JSDoc comments to infer types. Without tsserver, JSDoc is just a documentation tool.
@@azizsafudinI always find it funny when a TS dev say this kind of things. It would be quite pretentious from a low level language programmer but from someone coding in TypeScript it is really truly laughable. Do you think that you are a big guy because you know how to write types?
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.
this is wrong though, typescript is and always has been "opt-in". you don't have to enable the strict compiler options and you can disable noImplicitAny to be able to write javascript with type annotations here and there. whether you should do this is another question entirely but typescript was designed with that use-case in mind.
Ts is a superset of js, almost all js code is valid ts code. So, typing is optional. You may have used ts with some strict linter rules and that's why you were getting errors without the types
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.
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
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.
No matter what you should bundle your code when shipping a production "executable". Both for optimization but also for bandwidth. There's also downsides to rely on manual file splitting rather than chunk in that you have to manually manage how and what is downloaded and which times. Just creating a file that is then imported but could be inlined would end up costing additional roundtrips for no good reason and hurt UX.
@@dealloc these frontend things had nothing to do with js vs ts. (And i dont write js only for frontend) Al optimization are hiding that your code of used framework isnt optimal. You dont need all that fancy auto split stuff, just learn how it works, it isnt that hard. Learn the base, not a framework of library.
@@PieterWigboldus Depends on what you're trying to build and ship. But I didn't mention frameworks once in my post. I said when it's time to ship to production, you have to think about the user experience for end-users long term.
Most of the time thats a bad thing (it means you will be running code that the build step could possibily identify preemptively as incorrect). Not to mention most of serious projects already have a build step
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
Why do you want to remove comments. Let users understand also the source code. 20 years ago, you learn developing JS by checking other browsers. Source code is open, and free to manipulate for your own usage. Be open to users, and let them understand and play with the source. Also in Node.js you dont have to build, no reason to downgrade the code to be compatible with old systems. You build for a specific Node version, so no removing of comments needed. Syntax worse is an opinion. JDSoc makes it more clear that Types in JS/TS are just documentation you can lint, it is not for runtime. And in JSDoc you can also use TS types and interfaces for complex and external types. Why should you build your code in TS if you can just build JS code with the same help from TS to check the code.
@@PieterWigboldus simple, my docs aren’t always correctly type checked, the syntax is more verbose, copilot chokes on it, and it’s far easier to write an incorrect js doc than a ts type. Syntax highlighting is better and I have 100% type feature availability and I don’t have to refer to two sets of docs to write my code. No one is shipping their comments to prod. That’s ridiculous if you want to ship comments you ship your source maps. If the difference is just putting comments around my ts types I’m all for it if my compiler does it. There’s just no point to remove the compiler from my workflow unless I’m writing in console and then types don’t matter. Syntax is worse is my opinion but some opinions are shared by a larger audience as we can see when we browse through the number of open source projects who chose ts vs jsdoc. So while it’s an opinion it’s the more widely held ( and in my opinion correct)
@@thegrumpydeveloper than you have configured sometime wrong, because it came be the same. Eslint with JSDoc check can do something, not as far as Typescript. But with Typescript modus you have the same.
@@PieterWigboldus Because of size, bandwidth, parsing time, compression and extranous round trips. Let the bundler be smart about how to bundle your files into chunks, rather than manually having to build your architecture around optimizing the UX. Creating a new file for your one function would end up with an additional round trip for no good reason. Users doesn't care about your source code and how you don't bundle your code-until it actually effects them negatively and take up all their cellular data with a slow connection. If you want to be open to your users then open your source up, and link to the repository. Easy.
@@dealloc if you need that, your build process isnt optimal, you use eg inefficiënt frameworks. Keep it simple, that makes it fast. Everybody has today a fast device and most people also a fast connection. Optimizing isnt needed if you keep it simple. Checking and manipulate code is not what most people do, only some developers. But most developers makes it also hard to do. Tech people that it is possible, give them freedom. Think about the time of css zen garden 😉
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.
Haven't used JSDoc much, so I'm curious Do projects that use it ship the JSDoc to the client? Or do these projects still do things like minify the code? If yes, why is there a problem with compilation specifically? Since those projects would already need to have a build process, I don't see much of a difference. And if no, doesn't that result in ultra-bloated files to send to the client?
@@Trekiros The point is that you consume the JSDoc and source through your source code. To provide a better UX, you bundle your source code. Some libraries may provide pre-optimized bundles (like React), in such cases you can tell your bundler to use those when bundling, instead of having to re-bundling the dependencies. On top of this you can build individual chunks of your source and the deps, but it has tradeoffs depending on the granularity you choose to chunk your deps when it comes to caching and cache invalidation.
Yes and no, if you are doing a server side this is pretty much true, but as soon as your code hit the web client you'll need to convert to an older version of the standard and do minification, unless you're already coding in an old version of EcmaScript and don't care about minification
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.
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.
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…
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.
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.
i assume you're talking about a compiler from ts to native code which afaik does not exist. if you want to run ts without transpiling, you can use ts-node, but that's not native
What if you want to re use a complex object type in multiple files. Unions don't work properly. No utility types like Partial, Pick, Omit There's still a build step for production applications to remove the comments and minify the code. I personally don't see the utility in JSDoc, if you want Typescript like features just use it.
I remember making contributions that change .js to .ts and other devs get confused like another build step to publish as npm module, saying that .ts files are too complicated and so on. Many projects on npm refuse to use .ts and use either weird workarounds / duplicating logic in .d.ts or not adding any types at all, oss sometimes can be wild
this ....people keep acting like these are equal and one has build step and another doesnt. I dont get this, typescript's value imho never was in its "this function accepts this argument" ...this is nothing ground breaking, even php has some sort of "i want this type mechanism". The reason i use typescript is that i can do logic on types and crafting this very specific type mixed from 10 other, with subtracting some other from it. Then I slap it on a function argument, ye jsdoc can do this last step
You can still import TS types and interfaces inside JSDoc. Or define a JSDoc with typedef, and import it in another file with JSDoc. I work a lot last 2 years with JSDoc in TS mode and JS files, and if you work longer with it. Also you still dont need always a build step, see e.g. Node.js code, where JSDoc is superior to TS. And in frontend code, it is also not always needed.
@@PieterWigboldus Are you afraid of having a build step? In node.js you can use tsx to run any ts file without building. And don't you lose 2x time as you need to always switch between .d.ts and .js (this was so annoying for me). TS syntax is so concise comparing to jsdoc. Another reason why good dev imo will never use types in js with jsdocs is because non-null assertions are also available only in .ts and there are other restrictions. TS is a small price for big advantages but many guys afraid of having it.
JSdoc is a lot more convenient. Especially because you don't need to worry about sourcemaps and .gitignore. However, the biggest issue that _nobody seems to be talking about_, you cannot do everything that you can in TS. Especially non-null assertions are next to impossible in JS doc.
@@mattpocockuk totally agree. People that are seriously talking about jsdoc being a valid alternative either haven't done so past 'hello world', or they like simple type definitions with an 'any' now and again.
@@mattpocockuk You can... sort of. But it's bit of a hack. You can type the argument passed in: useState(/** @type {?string} */ (null)) This will correctly infer the return type, too. If the generic is only used for return type, you could also redefine the return type with @type. Though at this point you're in type assertion territory.
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.
This is also the answer to an argument I was having about PHPDoc Vs type hinting over in PHP-Land. If we're talking parseable code Vs comments, then parseable code always wins.
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)
JsDoc gives a better intellisense experience by default. If you want the same experience with TS, you literally have to write JsDocs in your typescript, thereby getting the worst of both worlds.
I had been using jsdoc in scripts lately mostly because its faster to itterate without the build step ( i feel that the transpiling takes an eternity when im editing short scripts and expect them to run instantly after a change)
i was wonder that if your library only intended to run with ts, and you really on types for safety. is there reason why would i compile my code while releasing it? i mean why not just ship ts files?
Firstly, you HAVE to ship declaration files to make the experience of using your library pleasant. If you don't ship declaration files, TS has to do a lot of work to figure out the types in those files, and your IDE experience using TS slows down. In theory you could ship .ts files and .d.ts files, but if you have to transpile anyway it makes sense to ship .js files which are more portable.
NPM is a JS ecosystem, the browser and Node.js also only understand JS. So JS is the basic of everything, that is running in production. TS only helps on development.
You can use JSDoc in two different ways. To simply comment your code, or to rely on as a type system. JSDoc comments are great for describing things. But I don't think you should rely on them to type your code.
For most apps, TS is better. However, there are a significant minority of projects where JSDoc is better. For example, my hockey team website where I have zero build tools on the CLI side and the only JSDoc typechecking tool is built into VS Code itself.
What the hell is this guy talking about. You don't need to transpile the code to run it, you just need TSC to lint it. Sure what's the difference between a linter that changes the syntax of your code making it useless in the target environment, and one that just tells you if types are correct? No difference I guess according to this genius.
sorry, but it's a completely wrong point. To validate JSDoc, you need TS and build step, BUT you don't need such things to run it. TS, you can't run without the build step (in browser or nodejs)
Literally zero of the benefits you mention about typescript matter if you're working in a pre-existing code base that you aren't able to migrate over to typescript. It also doesn't matter if you can't move over to typescript for a variety of other reasons. JSDoc has been incredible in allowing me to get a ton of the benefits of types without any of the friction of adding full on typescript. So while it would be great if I could use typescript at work, the truth is I don't get to at this time but at least I get JSDoc and I get to skip the extra build step.
JSDoc is kinda ugly, but it stands out in the code. There is a good visual sepearation between types and code. I like it that way. TS to me looks like a soup of code and types, I don't know what is what.
If you use JSDoc just for type annotation, sure, it's worse than TypeScript, but I think you are missing the point a bit as JSDoc is for documenting the code, and you should also pass the meaning of what variable a or b are, something that you can't do in TS. Personally I used both JSDoc and TS, and you don't need to set the type in JSDoc in that case, but you should just add the meaning of a function or variable. Once you combine the two, you get all the power of intellisense. It's not TS OR JSDoc for me, it's TS AND JSDoc!
@@mattpocockuk if that’s all you want, then yes it’s not the best way to use it, but it’s like using a fork to cut the bread, it’s not the fork that is bad, it’s just the wrong tool for the job
TS is awful. It gets complex very quickly and you spend more time programming types than developing your software. JsDoc is a great middle ground, and you can test as you go even if the types ain’t there yet. A great commit hook can save you from unfinished work being merged without the loss of productivity. I just don’t like the syntax, it could be better, but it certainly better than TS.
Wuh? What terrible IDE do you use where you need to run the typescript compiler and have a tsconfig.json to get type checking for JSDoc? That should be immediately functional in every modern IDE
aaaaaand it looks _really_ awful with import statements inside the comments when you are not just looking at an example with primitives. Just take a look inside the Svelte repo before you decide if you want this ugliness in your project
Yeah nahhh, this video aint it. While I do agree with your point, it is VERY oriented to enhance Typescript (which is fair due to it being your money maker). But plz, dont do this type of video without showing the trade off of each (only showing the good/bad side of one or the other)
@@mattpocockuk TS isn't just the "type" there is a whole bunch of wierdness from TS that we didn't account for, in special when we speak about Interfaces, this is a breaking point and usually bad at 50% of the time. Enuns that aren't enums and are just another breaking point. No compilation also means that the code you wrote will be the same, no mysterious TS magic to make the type system to work. The TS is just a "fancy" linter with extra steps. I can keep the list on and on. No type sucks, but between JSDocs and TS Wierdness, I'll take the docs all year long.
@@ShinSpiegel In JSDoc you can also import TS types and interfaces. Also the Enum is just some type for an object, and you can also use Enum in JSDoc. If you talk about type and type checking, the same can be done, but JSDoc doesn't need to transform the code, and replacing all the types with ... nothing, like TS do. I don't understand why some people think TS is such a different world, after all the code inside the method is the same, and types are removed in the build. Just write JS, and if you like types, add JSDoc. Keep it simple!
@@PieterWigboldusbecause it is. I'm limited by the constrains of the RU-vid comment. I'll write a blog post at some point in the future to better display the reason “why” TS and JSdoc aren't the same, and explain the whybecauae of it.
