Specify optional and named parameters

[domenic]

Closes #320.

---

Preview | Diff

[annevk]

This looks great, thanks for formalizing this!

I'm not entirely convinced we want the last paragraph however. Making that tradeoff seems extremely nuanced and I'd rather folks either use a struct or not name the parameters.

[jakearchibald]

Feels like we should call out positional booleans as bad practice.

[annevk]

If we really want to do that I guess that would further argue for special casing booleans in some ways.

[domenic]

Yeah, I dunno, it's OK-ish especially since it's all hypertext, but I agree generally it's not going to be a good time, and you probably want your booleans to be named.

[annevk]

It seems based on the discussion we should change this too, right? To only have examples with recommended practice.

[domenic]

Maybe. I'm unsure because it's part of the "narrative flow" of the section: it shows the algorithm evolving from unclear and inflexible optional positional arguments, to clear and flexible optional named arguments.

We could instead specifically explain that not only is this non-ideal because of the ordering restrictions, but also because of the presence of non-named boolean parameters?

[annevk]

Yeah that sounds good to me. I suspect that would work for @jyasskin too.

[domenic]

Done.

[jyasskin]

Yep, thanks. Note that this example-of-things-we-don't-want-people-to-do winds up looking the same as all the other examples-of-things-to-do. Vanilla bikeshed supports a heading="Bad Example" attribute to make it a little clearer, but that attribute doesn't work with the WHATWG style sheet's .example::before { content: 'Example'; } rule.

[jyasskin]

FWIW, I think Call foo with 3 and Call foo with "navigate" are not much better than Call foo with false, and Infra should encourage people to name those non-optional parameters. Perhaps:

Suggested change

	<p>Non-optional named parameters may also be used, using the same convention of marking them up as
	both variables and definitions, and linking to them from call sites. However, one should default to
	making non-optional parameters positional, for simplicity and uniformity. Non-optional named
	parameters should only be used when they significantly improve clarity, and even then it might be
	<p>Non-optional parameters may also be named, using the same convention of marking them up as
	both variables and definitions, and linking to them from call sites. Do this when it improves
	clarity at call sites. It is also

[jyasskin]

Yep, thanks. Note that this example-of-things-we-don't-want-people-to-do winds up looking the same as all the other examples-of-things-to-do. Vanilla bikeshed supports a heading="Bad Example" attribute to make it a little clearer, but that attribute doesn't work with the WHATWG style sheet's .example::before { content: 'Example'; } rule.

[domenic]

So, this has been sitting for a while. I'd like to get it landed. Outstanding feedback:

• @jyasskin's preference toward more named parameters, or at least against the current PR's avoidance of them, expressed in comments immediately above. I'm on the fence here. I like the idea of Infra giving guidance, but since this seems controversial, maybe Infra should be more neutral, and leave this up to editor preference.

• @jakearchibald's feedback in Named arguments and especially named optional arguments #320 (comment) that we shouldn't use <var> at call sites. Although I recognize the logic of his position, it feels a bit icky to have camelCased things that aren't <var>, and to have the typography at the call site mismatch the definition site. So I'm weakly for the PR as-is.

@annevk, any thoughts? And if anyone wants to chime with their perspective on the above, feel free to do so.

[annevk]

I think encouraging naming for optional arguments is reasonable, but I'm okay with not endorsing anything for now, especially as there is no tooling support either.

We could use <i> at the call site instead of <var>.

[jakearchibald]

With <var> you have to work around it not-really-being-a-var with <var ignore>. With <i> you don't need to work around it, so it gets my vote.

[domenic]

Alright, this might be ready to go then!

[jyasskin]

Thanks!