13

With a properly maintained JSDoc, almost any modern IDE can identify a type mismatch (of assignments, functions' signatures/arguments) and many other issues that a non-strongly-typed language introduces. Besides that, modern JS comes with a predictable variable scoping, hoisting-free behavior, modularization, built-in classes support, and many other.

In which scenario may TypeScript serve developer needs better than JS+JSDoc?

Mike
  • 14,010
  • 29
  • 101
  • 161
  • 1
    JSDoc seems to be able to simulate what typescript does however having so many comments in the code makes the actual code non readable. – Panagiotis Bougioukos Jul 17 '21 at 16:12
  • 1
    @Boug, the JSDoc types can be defined in a separate JSDoc dictionary while in the code itself only references will appear, just like JavaDoc, which is considered as a standard, does. – Mike Jul 17 '21 at 16:17
  • 2
    I can lie with JSDoc very easily and accidentally. TS makes it so that I have to lie more purposefully by saying "I know better than you TS, this is absolutely a number, I dont care if you think otherwise". JSDoc is the opposite where you have to always be saying what something is. – zero298 Jul 17 '21 at 17:24
  • @zero298, thanks, that's a good point. Unfortunately, someone 3 people considered this question as too general and closed it. – Mike Jul 17 '21 at 17:36
  • 1
    I've tried to make the question more clear. The "notes" were confusing the original question, and the actual question was asked twice with only different wordings. – Kamafeather Sep 30 '21 at 13:52
  • 1
    I voted for reopen, see if you can improve it even more. – Kamafeather Sep 30 '21 at 13:52

2 Answers2

8

I think this is a little weird of a comparison. JSDoc is documentation oriented, while typescript adds optional static typing to js. These tools do have some parts in common, they allow for type checks for example, but their purpose is different.

It's an interesting question though. I'd like to encourage a discussion on the topic, so I'm going to talk from my experience with the tools.

The main issue I have with jsdoc is that the following part is crucial:

properly maintained JSDoc

The usefulness of jsdoc for autocompletion depends directly on the effort and quality of the jsdoc comments. I found it hard to enforce in big projects. Complex types/interfaces are also a pain to describe and maintain, being extremely verbose. Ts on the other hand is a lot more concise than jsdoc.

Furthermore, types and interfaces in ts are first class citizens, and aren't just an addition for documentation sake. They are entities in the source code and can be exported for other modules to use. Type mismatch is enforced in the compilation process(and before). There are also mechanisms like generics or decorators, that come with ts.

Back to the enforcing guidelines part. With ESLint you can setup flexible rules that will allow you to fine tune restrictions/styles/guidelines for your types. You want rigidly static types? Or you want leniency?
You can have your exact needs enforced and hooked up to ci/cd if you want. In my eyes that's a big bonus when working on big projects.

Tooling is also an important factor, both jsdoc and ts are mature enough to have ecosystems around them. Although at this point in time jsdoc isn't an active project, while ts is extremely popular and has a huge community around it with lots of activity.

So it all comes down to your needs, if you're happy with what jsdoc can do for you and documentation is your main focus, then ts won't do much for you.

P.S. Ts and jsdoc aren't mutually exclusive. You can have both, although you might want to switch to something like TSDoc

EcksDy
  • 1,289
  • 9
  • 25
-1

Various Js compiler like Typescript and Closure officially supports type checking using JSDoc https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

It’s a valid option if you want to type check Js source code.

user1948585
  • 170
  • 1
  • 7