Add FAQ entry re: eval/Function

[mathiasbynens]

It would be good to add this FAQ entry to the README:

Does the hashbang syntax work within eval / Function?

Examples of confusion caused by the lack of clarity here:

• Normative: CreateDynamicFunction early concatenates bodyText ecma262#1479
• https://chromium-review.googlesource.com/c/v8/v8/+/1510792

[bmeck]

It would be allowed within eval since it uses Script as the parse goal, but Function does not and so it wouldn't be allowed. There are a fair number of evaluators and I'm hesitant to add entries for all of them.

[mathiasbynens]

What other evaluators are you thinking of?

[bmeck]

• AsyncFunction / AsyncGeneratorFunction / GeneratorFunction Language provided
• setTimeout(string, ...), setInterval(string, ...) Host provided
• HTMLElement.prototype.on* Host provided
• require('vm').* Host provided
• data:/blob: URLs (arguable if they are evaluators, but CSP recommendations roughly treats them as such)

I think that a list would be more confusing as it is trivia about APIs rather than about the proposal itself.

[mathiasbynens]

I wouldn’t expect any host-provided non-ECMAScript mechanisms to be mentioned in such a FAQ entry, tbh. Just having #12 (comment) as the answer would already help.

[bmeck]

Minimal entry added.

[hax]

Most programmers don't know which API use Script as the parse goal, and it will be painful if someone refactor code from the pattern which allow hashbang (source file, eval string, etc.) to the pattern which not.

[bmeck]

@hax that is true for all sorts of syntax that is only available such as return inside eval vs Function etc. Is this specific to hashbang comments somehow?

[hax]

@bmeck
Yes they are similar, but the direction is reversed in return case.

If someone see return, almost all people understand it should be in function, so they can wrap the code in function if they worry about that.

On the other side, someone see #!, they first need to understand not all parse goal support hashbang, even they understand this, they still need to know which api support #! because no simple way to ensure it always work except removing it.

[bmeck]

#! is something that only occurs in the start of files as thats the only place supported by OS/shells. I don't understand the difference, both require knowing where syntax is valid.

[hax]

@bmeck I suppose we are talking about refactoring code between "where"s. The difference is:

• It's simple to know put code contains return in a function (for example iife) will always be valid if u don't want care about "where"
• You are forced to know "where" for #! (though u finally understand the best way is just remove it)

[ljharb]

When transforming code, you must always know the intended parse goal and environment - it’s not something javascript, or every env, allows you to reliably infer. Once you know that, you don’t have to apply heuristics to the code - your tooling can already know how to handle it.

[bmeck]

If we use a different syntax that more closely mimics needing to be in the top scope like export the argument seems to remain that you still need to know where the code exists. You cannot wrap an export in anything to make it universally valid. In addition, adding an IIFE changes the semantics of what that code was doing as it prevents the abrupt completion return performs. Similarly, moving #! removes the interpreter directive support that it provides.

[hax]

@bmeck As #18 , we suggest treat #! as some sort of comment which u don't need to learn parse goal and know where #! exist.

The problem of export is about module/script, and it seems almost all APIs (except vm or creating script tag or future realm api) never support module so I think developers won't try send module code to those APIs.

adding an IIFE changes the semantics... moving #! removes the interpreter directive support...

Note we are discussing developer experience here, so argue that "you have to know these things" or "there is subtle difference" is not enough. Programmers tend to choose the simplest way as a solution and name it "best practice" with some possible "tradeoff"s.