the "types as comments" title is somewhat misleading

[slk333]

The proposal title mentions types as comments

comments in JS have a very clear meaning. Looking at the proposal body, we cannot find a single code example where types are provided as comments, except for the mention of JSDoc.

What we find instead is an explanation that the proposal wants to introduce types as "annotations", but this is buried deep into the proposal.

A lot of people will only read the title and expect types as comments, when they are in fact not provided as comments.

To clear things up, I think you change the title to type as annotations or type annotations

[wparad]

I mostly agree, but what does annotations even mean. I think people will misinterpret or jump to conclusions no matter what it is. Perhaps typescrypt-like typings could be an example.

[bakkot]

The syntax in this proposal is for comments. I don't know what distinction you're drawing between "comments" and "annotations", but colloquially "comments" means "syntax you can optionally add which is informative to readers but ignored by the thing executing the code", which is precisely the sense used here.

[joshgoebel]

which is precisely the sense used here.

I think when many people hear "comments" they immediately think of comments in the [existing] syntactic sense ie:

• //
• /* ... */

This proposal is suggesting adding TS-like type annotations (best word IMHO) that are ignored. If this proposal were accepted I personally would find it strange if someone referred to these as "comments" rather than "annotations"... Semantically I would expect a good code highlighter to highlight them as keywords/types (as one might imagine TypeScript is currently highlighted in a good editor) - not as comments.

So I do think this would be improved if the proposal used the word "annotations".

[wparad]

wait is there such a thing as a comment which is not // or /*? If so, then you've just started by taking this proposal back ten steps before it was even started. The number of people that would think a comment could be anything else is minuscule part of the developer population.

[ljharb]

The specific difference is that comments do not have explicit attachment; this proposal provides comments that are explicitly attached to specific things.

@wparad there's HTML comments :-p <!-- this is a comment and --> this is also a comment

[wparad]

--> this is also a comment is it? What docs say that is a comment? Comments aren't rendered right? That is rendered as real text on webpages isn't it?

[DanielRosenwasser]

The way that this feature is discussed colloquially, taught, or even possibly specified might not specifically bother to call these "comments". We used "types as comments" as a way to build up intuition in how we build out this feature - as a cognitive device for how to approach the current proposal.

Maybe that seems like an overkill reason for why we've used that as the name; however, much of the time, we'll receive a question around whether types should behave a certain way which is easily answered with a response like "no, because they would just be like comments".

If you would ike, you can probably think of it as "optional erasable type syntax for JavaScript", and at the end of the day that is how a lot of people will view it as well.

[wparad]

Depends on what the point of the title is, because if it is "to immediately know what the proposal is about without A LOT OF EXTRA context", then most aren't going to know what erasable types means.

It is still better, but then it would be even better as build-time only types

[matthewp]

I also find calling it "comments" confusing as I said in https://github.com/giltayar/proposal-types-as-comments/issues/49#issuecomment-1063974189.

In every programming language I've ever seen, a comment is an arbitrary sequence of characters that is placed between some start and end character sequence. The fact that these type annotations do not allow an arbitrary sequence of characters is what makes it very not-comment like to me.

[wparad]

https://github.com/giltayar/proposal-types-as-comments/issues/79 => type hints: :star_struck: @bl0cknumber

[giltayar]

While the title of "types as comments" is a good one to build intuition, going further down the line it will probably be changed.

I'm seeing more and more use of the term "type space" to suggest that we are allocating spaces in the syntax where types can be added. Which I kinda like and am going to use going forward.

[orta]

So far, no other proposal name has been as useful at describing the underlying concept of the proposal without caveats and side-explanations as 'types as comments' - it's a bit like how TypeScript had/has described itself as a superset of JavaScript, accurate enough to get the idea across but inaccurate when you examine it with a microscope. For this proposal you can write types, and they are treated like comments to the engine. It's a pretty good match of idea to explanation.

more use of the term "type space"

This is a term we use in the TS docs a few times too, because it's a good way to differentiate eval-run code and erased type level code. For folks without erasable type experience though it requires a bit of building up to though.

Some ideas based on the above discussions:

• Proposal: Optional type syntax space
• Proposal: Ignored type hints
• Proposal: Skipped type syntax

But I'm not sure they really get the idea across as easily as 'types as comments'.

[benjamingr]

I'm... not sure why bikeshedding the name of the proposal itself is useful here since this has no impact on the proposal itself.

The name is written (as said above) from an engine's PoV to emphasize this is something engines can do cheaply without impacting runtime semantics which I think is important to emphasize but really - the proposal name is really only that: the proposal name. It has no bearing and doesn't actually appear in the spec text.

[wparad]

Because people come here with the expectation that the proposal is about adding explicit support for a JSDoc like solution. If you care about the community contributing positively then you change the messaging. As you pointed out it has no functional purpose, so we should absolutely change it to something more easily understandable.

[matthewp]

@benjamingr Of course how you describe a proposal affects how people reason about it and how much they are able to contribute to the discussion. If I called a proposal "function overloading" but it was actually about private object fields there would be confusion and bad feedback would result.

For example, I was under the impression that because this was "comments" that an arbitrary character sequence could be placed after the : but now I realize that's not the case.

[ljharb]

Mainly because before stage 2, tc39 proposals are intended to describe a problem, not a solution, and the proposal name ideally is worded around the problem. “Types as comments” describes a solution, not a problem.

[giltayar]

When we started the proposal, I wasn't very happy with "types as comments". But I believed that by stage 2 the name will change based on the terminology that will likely come out of fleshing out this proposal to something more specific. Given that I don't know yet what the specific solution is, and what the terminology will be around it, I decided that it's too premature to argue about it.

But I believe the discussions here are great for fleshing out the terminology around this proposal!

[jimmywarting]

This was my first impression also: "Wow, are jsdoc comments finally going to have some special meaning if you where to turn on "use jsdoc" or some preferences in dev tool?" nope... i sooo hoped that it was cuz all this will introduce is another syntax into the javascript language. with all this new syntax then we are never going to be able to get away from transpilers like babel, typescript, esbuild, webpack etc, I'm tired of this tools... i did really hope that it would be optional somehow. and this would be backwards compatible. Can we just take a break and only introduce new web api's that can be polyfilled instead of adding new syntax all the time?

This is just another typescript like annotation, I think you should change the title!

Maybe it isn't the javascript faults. it could just be that we have a bad IDE... typescript dose virtually nothing for us in terms of usability. I wish google built a new editor that could actually hook into the v8 engine itself give you feedback of what the actual things dose. and maybe even have a actual understanding of the WebIDL conversion stuff that is actually going on behind the scenes. I so wish this could happen so that we could get rid of all d.ts files so they are no longer needed. a Greate IDE would know what the actual thing dose like casting things into strings when it expects it. it's totally fine to do eg: fetch(new URL(...)) but TS don't see it that way. A IDE that can understand all new feature and the WebIDL conversion that is going on would be the editor of my choice. then i would ditch vscode in a heart beat... typescript don't have any knowlage of toPrimitive stuff. Typescript don't even know what things return, it's just all guessing - like a HTMLInputElement have this kind of properties but when they add a new value.asTemporal it would break cuz it dose not match the annotated type cuz it would have more properties added to it

can you imagine if we could get all the new feature from like the new whatwg/fs for instance without actually having to wait for microsoft type definition to implement it. which they won't do until at least x browser agree to implement it. imagine an ide that hooks into the devtools-protocol and giving you live feedback

Javascript is a dynamic language and it is nothing wrong with it. it can also be seen as a beautiful things cuz it also makes it easier to learn.

typescript is only seen as an annotation to declear what something is how how it should look like, it never enforce strict type checking and that's the problem.

I think i did like this proposal was somewhat more: https://github.com/sirisian/ecmascript-types that actually went into the depth of adding new types to the language itself like declearing an actual Int8, float, double variables and not blindly rely on browser to represent numbers as whatever it things is best

there is a differences between annotation and actual types... this proposal is just optional annotation. i don't want that... i want real Int8 typed variables that allocates exactly what i decleared the variable to be.

[sdras]

Thank you @giltayar for being open to this discussion for adjustment eventually.

I'm... not sure why bikeshedding the name of the proposal itself is useful here since this has no impact on the proposal itself.

Because it is affecting the proposal: people are confused. Whether or not it is technically accurate is like saying it doesn't matter how your code is written- of course it does because code is also for communication.

Comments do call to mind a different kind of implementation, and the point earlier that we would expect syntax highlighting in an editor to not treat this space as comments is a solid argument.

@orta's suggestion of Proposal: Optional type syntax space was a great one, IMO, it would be much more clear what the expected behavior would be.

[trenttobler]

Also, types as comments are IMHO a better solution than requiring every javascript execution engine to update to support new syntax. Push the problem from being an engine change, to a tooling change, and I think the idea of adding power of type annotations and definitions is an interesting one.

If one is committed to a typescript-like syntax, for example, the following would run on existing browsers and js engines:

/*:type Person = {
  name: string,
  age: number,
}*/

function addPerson(name /*: string*/, age /*: number*/) /*: Person*/ {
  ...
}

would not require any updates to the runtime, but now tooling and IDEs could be enhanced to support rendering this in a more 'annotation' like way, masking or de-emphasizing the comments and emphasizing the inner content.

JSdoc itself could already serve a lot of this purpose -- the problem is now one of updated tooling, rather than figuring out how to get those few who cling to older technology from not being able to run your latest webapp store that uses different syntax.

[wparad]

I don't think that is a valid argument, because then the conclusion would be if we wanted tooling support, to just use one of the existing ts, flow, etc... Which already has tooling support. The only reason to do it this way is if you wanted browsers to make a change

[trenttobler]

Does TS, flow, etc. tooling support the flow where no tsc compilation phase is needed? E.G, if I open a file.js in a text editor, I see function foo(arg /*: string*/) in the ASCII representation of the code, but when I open it in VSCode or eclipse, I see it displayed/rendered as function foo(arg: string) ? The proposal seems to want to skip the compilation stage that most toolchains have; if this is the intended target of the proposal, then it feels to me that the better solution is to change how the source files are encoded as ASCII/UTF, rather than changing syntax... because it's easier to upgrade tooling (IMHO) than to upgrade runtime engine (js parser/execution in browsers).

Anyway, just my thoughts; the proposal seems it would create an environment where you would continue to need the compilation stage regardless to strip out all this annotation, in order to support backward compatible engines that lack this support.

[wparad]

It absolutely could but just changing the tools, but the question is why, I can go out today and write you a TS => hack comment converter that you can install in VSC code that dynamically replaces what you look at. But that has nothing to do with javascript

[trenttobler]

It absolutely could but just changing the tools, but the question is why, I can go out today and write you a TS => hack comment converter that you can install in VSC code that dynamically replaces what you look at. But that has nothing to do with javascript

Did you read the proposal? It seems that was the goal - to provide syntax that could skip the compile/transpile step. To add type safety to javascript, and this thread is about it being somewhat misleading, in the sense that it is not doing so by using "types as comments" strategy, rather, it seems "types with new javascript syntax" would be more appropriate? (Refer to the diagram https://devblogs.microsoft.com/typescript/a-proposal-for-type-syntax-in-javascript/ - and you might understand why I chose to use typescript as an example to suggest type annotations compatible with js without a transpiler and without a compiler.)

I was just commenting on that strategy, and the possibility of a different, alternative strategy true to the proposed title. I think it's an interesting idea. It also isn't such that you must not update the runtime, only that it would not be required in order to run the un-transpiled, un-compiled code because it would backward compatible to the existing javascript syntax.

As to why, well, enhancing the runtime would not necessarily be disallowed --- with types specified in this way, if it were provided to an updated javascript runtime engine, that engine could provide stronger guarantees during jit compilation, and produce more performant / efficient code. For example, if it knew it was a number, and always a number, in a variable, it may just use it as a value type and pass it around without any GC or allocations needed. It could also generate errors when type mismatches or other issues happened, that the more legacy engines would be unable to do (even if they could run the code without any changes or backward transpilation step.)

Is it a good idea, to do so anyway? I am not convinced either. I think it adds a level of hackiness to the raw encoded form (I.E, making it harder to edit with simple text editors.) On the other hand, if the performance optimizations could be done on this same syntax, and making a runtime engine that used this type annotation giving you 3x-10x boost in performance, maybe it's worth it.