[maxyme]

My team has recently focused on adding JSDoc to most of our codebase and I've been thinking, JSDoc provides essentially all the benefits (and more) of typescript from a maintainability aspect and contains none of the headaches (outdated definitely typed definitions, fighting with types...). As long as you use something to validate the JSDoc comments (like the JSDoc eslint plugin) they are extremely helpful in ways very similar to typescript. Language Servers like that in VSCode (tsserver) will inherit types from JSDoc comments and provide useful annotations with both the types and descriptions. They can even be used to show code examples or statically generated into webpages.

If your only argument is to use typescript for maintainability reasons doesn't using JSDoc extensively both solve and improve upon that goal?

[alangpierce]

I guess depends on exactly how you use JSDoc, but it sounds like you're talking about relatively informal documentation with some best-effort machine validation. My experience is that you don't get anywhere close to the confidence that you get with a real typechecker. Docs can be overlooked, docs can be misinterpreted, docs can get out of date, docs can be wrong by mistake. And, inevitably, if you have many people working with the same code over the course of years, these issues will be common. Having an actual typechecker avoids all of these problems, at least for documentation of data formats.

If you do mean annotating all types with the thoroughness that you'd annotate TypeScript code, then really you're just writing TypeScript in JS, and TypeScript is a much more concise language than JSDoc for that.

[cozuya]

THANK YOU. I thought I was going crazy by being apparently the now 2nd person in the world who is perfectly happy with normal JavaScript plus slapping on JSDoc (mostly via custom vsc snippet) onto non trivial functions plugged into eslint. If I could make it fail lint when JSDoc doesn't exist I'd be perfectly fine with the maintainability of what I'm doing.

[chrischen]

You can try something like facebook's flow which can be done as comments so no transpiler is needed.