Naming things

[mihnita]

We've been using all kind of names in our separate proposals, and never managed to unify.
But names are important, and it's about time to decide on this.

Some examples:

• Variable / argument / input data.
• Local variable / alias / macro.
• <evertyhing>Ref
• placeholders / placeables / ???
• annotations / functions / ???

TODO: add more

[mihnita]

Comments migrated from the slides

---

Slides comment, Mihai Nita (@mihnita), 1:47 PM Apr 21

Maybe bikeshedding, but I don't think this is a good name.
And names are important, because they can help or impede understanding.

If these are things that the user passed to .format, and will end up passed to the formatting function, then they are arguments, or parameters if you are in the function definition or the function caller.

But not variables. Which exist outside the function definition / function call.

int e = 2.718 // variable
int pi = 3.1416 // variable

foo(pi) // pi is now argument

function foo(bar) {
  // here bar is a parameter
}

In the example above e is a variable. But the function would never see it.

[mihnita]

Comments migrated from the slides

local variables

---

Slides comment, Elango Cheran (@echeran), 11:37 AM Apr 21

Is this what was also referred to in other proposals as aliases or macros? If so, can we use one of those other words? "local variable" implies something is varying, but the alias/macro functionality can/should really be seen as creating a local immutable binding.

---

Slides comment, Eemeli Aro (@eemeli), 12:31 PM Apr 21

Yes. The name for this concept was discussed at some length during the MFWG call on 7 Feb. At that meeting, the term "local variable" was seen as less conflicting than either "alias" or "macro". This discussion is summarised here: #220 (comment)

---

Slides comment, Elango Cheran (@echeran), 1:04 PM Apr 21

On this topic, the only reference I see in the notes / issue is: As both "alias" and "macro" have strikes against their use, let us refer to the entities under discussion as "local variables".

As I see it, "local variable" has a strike against it, too. IMO, the strike is bigger than the other two options. I've seen the other two terms have overloaded meanings in different places and people be okay with that. In contrast, I just don't recall "local variable" used anywhere outside of a programming language, and it implies a particular meaning.

[echeran]

• Variable / argument / input data.

Similar to above, I think "variable" has a distinct meaning in a programming language context -- something whose value can change. If we're talking about a pattern {Hello {$name}!}, I would like to call {$name} the placeholder, and the argument is $name. By the time we see a value for $name, it does not change.

• Local variable / alias / macro.

Same logic as above. I would prefer "alias" over "macro", while "local variable" is a misnomer.

• placeholders / placeables / ???

I can't reproduce the exact discussion where we agreed "placeholder" is preferable, but as I remember it, placeholder it's a standard term in l10n tooling and specs, whereas the "-able" suffix in software almost always implies an interface (ex: Java JDK). The result of that discussion was incorporated into #30

[stasm]

By the time we see a value for $name, it does not change.

I think this is crux of misunderstanding: we choose different moments of a translation's lifetime when we pick the name for variables/arguments.

You say by the time we see a value..., and you're right that given the following message:

{$userGender: equals}
    masculine [{$userName} added a new photo to his album.]
    feminine [{$userName} added a new photo to her album.]
    * [{$userName} added a new photo to their album.]

...the value of $userName is constant during a single formatting operation at runtime.

At the same time, this same message can format as Elango added a new photo to his album. or as Staś added a new photo to his album. The user's name varies between formatting operations; it is in fact variable.

Furthermore, I agree with you and @mihnita that if we look at a message as a blackbox with input and output (like a mathematical function), we could call them arguments. The trouble I see with this name, however, is that at the same time we also plan to have a function registry with functions, and these functions will take arguments. For example, in {"1" :number maxFractionDigits=2}, the 1 literal is an argument to the :number function. This is why I'd like to use a different name than argument for input data that comes from outside of the message (like $userName).

[stasm]

Re. the placeholder, do we want it to be the name of anything between {...} that's not translatable content, including UI elements, standalone function calls, etc.? Or just those cases when we format some input data coming from outside the message?

Assuming the following syntax for UI elements:

[{button}Submit{/button} or {link}cancel{/link}.]

Are {button}, {/button}, {link}, and {/link} also placeholders?

[eemeli]

Are {button}, {/button}, {link}, and {/link} also placeholders?

I would say yes. I think placeholder is a catch-all term for a container within a message that can either hold an expression or markup. If we eventually add message references, they too would be in a placeholder.

Also, I don't think the term "placeable" is really useful due to its similarity/overlap with placeholder. Using both and defining them with different meanings would be pretty certain to cause confusion.

[stasm]

Also, I don't think the term "placeable" is really useful due to its similarity/overlap with placeholder. Using both and defining them with different meanings would be pretty certain to cause confusion.

Agreed. I am to blame for (re-)introducing placeable in the EBNF of my January WIP. I suspect it was muscle memory from Fluent times. Let's change it.

[echeran]

...the value of $userName is constant during a single formatting operation at runtime.

At the same time, this same message can format as Elango added a new photo to his album. or as Staś added a new photo to his album. The user's name varies between formatting operations; it is in fact variable.

Hmm, what you described is analogous to a parameter when you write the source code for a function in a programming language. The values assigned to a parameter should be constant within the scope of the function, but of course, the argument values passed into those parameter names can differ from one invocation to the next.

I think the real difference here is that most languages are not immutable-only-ish, so you may use a local variable to give a name to something, even if you don't mutate (vary) it. (If not for readability or caching the result of an expensive operation, it wouldn't make sense to create a mutable variable within a lexical scope but never mutate it.) When you are using an immutable-only programming language, you can't call it a variable, so you call it a binding. I think binding is also a better choice here.

But maybe I'm the only one who thinks the phrase "local variable" evokes the idea of mutation in a programming language, and that it doesn't fit. If so, then that's fine, although I wouldn't agree, still.

Furthermore, I agree with you and @mihnita that if we look at a message as a blackbox with input and output (like a mathematical function), we could call them arguments. The trouble I see with this name, however, is that at the same time we also plan to have a function registry with functions, and these functions will take arguments. For example, in {"1" :number maxFractionDigits=2}, the 1 literal is an argument to the :number function. This is why I'd like to use a different name than argument for input data that comes from outside of the message (like $userName).

Yeah, I'm not too particular here. I agree that maybe different names can help. Existing ICU MF calls the names "arguments", and I think the EM proposal called the logical key-val entries like maxFractionDigits=2 ... as "options".

[markusicu]

• "Placeholder" seems good.
• "Option" for a key=value pair after a function name seems good.
• "Argument" seems good for the input that a function works with. Not sure if "argument name" should include or exclude the $.
• I have been using "value literal" for an argument given as a (literal), trying to not collide with other terms.
• I think it's ok to also talk about "arguments" for the objects that a caller passes into the message formatting library. They will usually be provided in some kind of Map from name strings to mostly-opaque value objects -- "argument names" (suggesting that that term should exclude the $) and "argument values".
• In the proposed compromise syntax I use "named expression" for what others have called "variables" or "macros", trying to avoid ambiguity and trying to be more descriptive.

[mihnita]

All names (from Marcus's comment) sound fine to me.
And I am tempted to say that "$" is not part of the argument name (I in fact started writing down why, only to discover that it is the argument Marcus makes in the bullet 5 (the one before last)

[mihnita]

I would like to "touch" this one and maybe schedule some names for discussion.

The current spec was a bit of "in a rush", with focus mostly on "let's get it to a decent shape for the ICU tech preview"
So we focused on a lot less on names.

But it might be the time to visit them?

Examples:

Variable

Kind of suggests that it is mutable, and it is evaluated at definition time
See #299

Operand / Annotation / Function

Expression ::= Operand Annotation? | Annotation
Operand ::= Literal | Variable
Annotation ::= Function Option*

But we don't apply an "annotation" on an "operand". Or going a bit deeper, we don't invoke a "function" on an "operand"
Operators work on operands.
Functions work on arguments / parameters (depending it it is at definition or invocation time. But not on operands.

Declaration

Is that section Declaration, or Definition?
In C/C++ extern int x; is a declaration, int x = 42; or int x = foo(bar); are definitions.
https://www.geeksforgeeks.org/difference-between-definition-and-declaration/

I think that let $foo = {$count :number precision=2} looks more like a definition.

[aphillips]

Does the adoption of the abnf answer this issue? The names in the abnf are specific and become our jargon?

[aphillips]

Closing per 2023-06-19 telecon discussion