JSDoc: Misleading Argument

[nweldev]

« Why not stick to existing JS comment syntax?

Although it is possible to define types in existing JavaScript comments, as Closure and TypeScript's JSDoc mode do, this syntax is much more verbose and unergonomic. »

This statement is absolutely true when comparing JS with JSDoc to TypeScript (before any transpilation).

Yet, the goal of this proposal is to add type annotations that are ignored by the engine.

A developer reading a JS code in the browser (e.g. when debugging) should therefore ignore type annotations too. Ignoring the type annotations will be more difficult in this context, as they will be intertwined with the meaningful code.

Debuggers could hide the type annotations or make sure they don't stand out (for example, with a grim colour). This would require additional developments.

On the other hand, comments are specifically dedicated to this usage: to make a clear distinction between zones for the interpreter and zones for the human readers and additional tools.

[orta]

I'm trying to get a sense of what you think is misleading in the original statement - are you saying that because someone could put anything in the syntax space reserved for types it would be harder to read that same code when debugging?

[benjamingr]

On the other hand, comments are specifically dedicated to this usage: to make a clear distinction between zones for the interpreter and zones for the human readers and additional tools.

Comments can already be inline (i.e. / foo / ) and "intertwined" with non-comment code (by design). Engines and developer tooling already color them differently for the reason you mentioned.

So this proposal doesn't change anything in that regard other than making it more common?

[nweldev]

@benjamingr Exactly my point. For now, comments are separated using a "separator" (/* foo */ or // bar). It's a common use case for all languages. People and tools are used to it.

This proposal would introduce "comments" without using this syntax ("separator"). People and tools will need to "adapt" to it. To exactly know the specificities.

[nweldev]

@orta Not at all. I'm saying that because it would be some kind of exception outside traditional comments scope, without using clear "separators". I see no problem with people putting anything they want it comments :slightly_smiling_face:

[simonbuchan]

To be clear, the proposed problem is that it can be visually ambiguous what is part of a type annotation, making it more difficult to read? While this doesn't seem to be a problem in practice in my experience, it is technically true, I guess?

That's not what the paragraph you're quoting talks about, though:

[JSDoc] syntax is much more verbose and unergonomic

This is, as you admit immediately, pretty incontestable. And hardly surprising, and perhaps worth the trade-off depending on your situation and taste anyway. And not being made illegal by anyone.

[nweldev]

@simonbuchan With this simple issue, I'm just trying to keep our focus on one very simple feedback for the proposal itself: IMO, the quoted argument is misleading. I don't believe JSDoc, in the context of this proposal, could be presented as "unergonomic".

JS with JSDoc is, indeed, unergonomic compared to Typescript (whole TypeScript, with type checking, compilation, etc.). Writing the same typing with JSDoc is more tedious than using TypeScript directly.

But this proposal doesn't talk about that. It doesn't propose to add any actual type checking whatsoever. So, here, we're only talking about adding a new syntax for comments. In this specific context, I believe adding another type of comment could be unergonomic.

To illustrate my point: right now, we only have two syntaxes for comments (/* ... */ and // ... <LineTerminator>):

function foo(bar /* Ut enim ad minim veniam */, baz /* Duis aute irure dolor in reprehenderit in voluptate */) {
  const hello = world; // Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum
}

Any developer can clearly identify when the comments begins and ends. It's, IMO, pretty ergonomic.

This proposal is introducing a new kind of comment, without a simple and clear definition of what does actually separate it from actual code:

function foo(bar: Ut enim ad minim veniam, baz: Duis aute irure dolor in reprehenderit in voluptate) {
  const hello: Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum = "world";
}

My 2 cents, besides the question of "ergonomy": Having a clear definition of the associated grammar could help us better discuss these questions. I could be on board with a proposal like that (i.e. where the only focus is to define a simple, clear, and maybe more ergonomic additional syntax for comments). Here, I kind of feel like the proposal is comparing apples to oranges.

[simonbuchan]

There's a tentative grammar already in the proposal, it's very narrow, and directly based on Typescript. I'm working on a general grammar, but there's technical issues I'm trying to figure out to make it useful.

In not sure how your argument shows that arbitrary type annotations are not ergonomic? Just because they're long? They pretty clearly end at the comma, close paren or equal sign.

[theScottyJam]

I'm going to respond to a concern from another thread (#119) over here, because I feel it applies to this thread more.

@David-Kunz I don't find the reasoning for why the proposal shouldn't mention JSDoc convincing, it is simply saying the existing option Typescript (and other languages!) users have to get the stated goals is not great, hence the desire for support for more native syntax. Proposals should attempt to anticipate questions the committee will have to show that it's at least worth the time for them to think about it.@David-Kunz I don't find the reasoning for why the proposal shouldn't mention JSDoc convincing, it is simply saying the existing option Typescript (and other languages!) users have to get the stated goals is not great, hence the desire for support for more native syntax. Proposals should attempt to anticipate questions the committee will have to show that it's at least worth the time for them to think about it.

So, I too find the JSDocs section a bit misleading, but perhaps for slightly different reasons than what the O.P. of this thread explained. I feel like the JSDocs section is a incomplete, and a bit misleading. Yes, it's important to explain that JSDocs are more verbose and less capable than TypeScript, which is why this particular existing system isn't great. However, this doesn't prove their conclusion at the end of that section, which is:

For these reasons, the goal of this proposal is to allow a very large subset of TypeScript syntax to appear as-is in JavaScript source files, interpreted as comments.

In reality, all we should conclude from that section is the fact that JSDocs isn't a great tool for providing types into JavaScript, which makes complete sense, It was never designed to be used as a powerful type system, it was mainly designed for documentation. There's much more terse and flexible ways to provide types in comments, Flow has done this, and TypeScript could choose to do it as well. If they want to reach the conclusion they're trying to draw, we ought to show why a types-in-comments system that's specifically designed to accomplish this objective will still fall short and be too verbose. Perhaps, another section discussing Flow's types-in-comments system would greatly help with this point and make it feel less misleading.

[nweldev]

@simonbuchan My bad, I didn't saw this change.

For reference: https://github.com/giltayar/proposal-types-as-comments/pull/73