☂️ Consistent terms for language features

[MaryaBelanger]

What information is missing?

We need consistent and user-friendly terminology across our docs for various language features. We should start standardizing the terminology we use for topics/ideas that have more than one word/phrase to describe them, by choosing one, defining, and sticking to it. A couple of examples:

• The ! operator following an expression that will throw an exception if the value of the expression is null. It gets called several things like null assert operator and non-null operator.
  • Propose new name for "Null assertion operator" #5252
• Instance fields are sometimes called 'fields', sometimes 'variables', and sometimes 'instance' is dropped because it's assumed to be clear from context (which might sometimes be valid).
  • (conversation below)
• Very subtle but meaningful differences like subtype vs. subclass
  • Glossary entries for "Subtype" and "Subclass" #4958
• Function vs. method
  • [Effective Dart] Add function definition to glossary #3602
• (future) implements for classes vs extension types (probably)
• etc.

The concern is that having different terms might be confusing and definitely makes searching harder.

Please add more ideas in the comments

How would you like us to fix this problem?

• Add to glossary page, possibly include synonyms for variable terms
• Once standards are defined, go through the site and make sure the same term is used consistently (as much as possible)

[parlough]

I'm not sure if it's a coincidence? But, I thought a lot about the non-null assertion operator yesterday: dart-lang/linter#3008 (comment). Probably in the wrong place, but it was relevant to my response :P. I'd really like the team to come to a conclusion for that one, and it's better to solidify earlier rather than later. Almost every person has a different name for it, sometimes inconsistent between the times they discuss it 🤣

[parlough]

In terms of the non-null assertion operator, maybe we just need to make a dart-lang/language issue, ping the entire language team, and get that discussion over with. In the end, we just need a term. I am biased towards non-null assertion operator since it's familiar to developers coming from other languages, but I will accept anything.

[MaryaBelanger]

Wow, thanks for the write up!

I'm not sure if it's a coincidence?

Not a coincidence, @bwilkerson just told me that this and similar conversations have been going on.

maybe we just need to make a dart-lang/language issue, ping the entire language team, and get that discussion over with

I think you should definitely create that issue with basically all the text from your comment.

Another option is I could create a PR here, and ping the language team / others on the team to review it? I'll take your choice, define it in the glossary, and go through the site and replace the existing terminology. PR for a couple reasons:

• people get way more involved in PRs
• would let people be able to see the change in action / evaluate it differently.

What do you think?

[parlough]

I'm not fully sure it needs to go in the glossary, kind of because we haven't fleshed out if that makes sense for all language features. But we can always remove it later if needed, so I'm fine with that too.

I love the idea of making a PR starting with dart.dev, as it adds a little 🔥 to the feedback, and could likely get done quick. But that's only if you have a term you're happy to start with :)

[parlough]

Oh wait, sorry I see you mentioned "Add to glossary page, possibly include synonyms for variable terms". I think it's a good idea actually, whether we do it for other operators/language features or not.

I look forward to your PR :D

[parlough]

Instance fields are sometimes called 'fields', sometimes 'variables', and sometimes 'instance' is dropped because it's assumed to be clear from context (which might sometimes be valid).

The following is a lot of Parker rambling and incomplete, feel free to ignore:

This is another one I've thought A LOT about over the past few years, but never could come to a final decision myself on how to best solve this. I think the issue arose because some writers/developers would always use "instance variables" and "static variables" to be consistent with the Dart specification which does not use <static/instance> field for those terms, while others are very familiar with using <static/instance> field.

Beyond just the website, there's also a disconnect between the spec and tools too, diagnostics and their messages in particular. That's perhaps because Brian came from a Java world, where while "instance variable" and "static variable" (as well as "class variable") are used in the Java spec as well, I've mostly never seen those terms used in practice. It could also be a deliberate choice because "static field" and "instance field" are perhaps more familiar to users, which is what makes the solution to this problem extremely hard to me.

I'm also pretty sure almost everyone uses the term "field initializer" instead of "instance variable initializers", despite the second being more precise.

I believe the the current term grouping situation is roughly like the following?

• Variables: instance variables, static variables, library/top-level variables, local variables
• Fields: (most often) instance variables, (depending on context) static variables
• Instance members: instance variables, instance methods, (instance) getters and setters
• Static members: static variables, static methods, (static) getters and setters
• Members: instance members + static members that are allowed in that declaration context
• Extension members: instance methods, static methods, getters and setters in an extension declaration
• Constructors: Not members, not methods
• _Functions: Leaving for a separate discussion :).

Perhaps we can start by adding some of the above terms to the glossary, then from there, collectively determine a preliminary set of rules to begin working towards. I'll try to follow-up on this thread with my current thoughts on what the rules could start off as and my rationale for those decisions.

---

Two thoughts I already feel confident about though:

• If referring to a specific variable by saying "the x variable", the only time that the type of variable (instance, static, library/top-level, local) should be left off is for local variables. Even then, consider whether adding "local" might improve clarity.

• "Class variable" has sometimes been used interchangeably with static variable/field. We mostly have avoided it on the Dart site, which is good. I feel this term should not be used, outside of a passing reference to direct to static variables. Programming beginners can struggle with class/instance/object as terms, and static provides a distinctive difference. "Class field", while rarer, has similar issues: for someone unfamiliar, "class field" could sound like it just means any field declared within a class declaration. I think(?) Java uses "class variable" because it can also refer to variables in interfaces, which are implicitly static, but I'm not sure Dart has anything like that.

[parlough]

Maybe I'm making it too complicated or being too pedantic, but it's really challenging for me. There are educational benefits to consistency, preciseness, and familiarity. In some of these cases, it just seems there's no way to have all three.

I will note that I'm personally leaning towards consistency and preciseness by sticking to the specification's naming (in most cases). I think those help more in the long term, while familiarity only helps initially. Beyond that, I think can artificially help/prop-up/bandaid familiarity with tooling like hover definition support for instance variables!

[eernstg]

@parlough wrote:

There are educational benefits to consistency, preciseness, and familiarity.

Agreed!

In some of these cases, it just seems there's no way to have all three.

We could perhaps note that consistency makes familiarity easier to establish, because a limited amount of experience will cover the whole system pretty well.

A couple of comments, using specification documents as a frame of reference:

"Class variable" has sometimes been used interchangeably with static variable/field

I believe that phrase has now been eliminated from all specification documents. It is now 'static variable'.

Also, we used to have 'static function' in the language specification, meaning "a library function or a class/mixin/mixin-class/enum/extension member declaration of a function that has the modifier static". Understandably, there was no end to the confusion caused by the fact that a 'static function' wasn't just a function whose declaration started with static, it was those functions plus top-level functions; but luckily we don't have that any more.

Unfortunately, we have 37 occurrences of 'static function' in other specification documents (feature specifications), but I hope we can use 'static method' to denote a member declaration (class/mixin/mixin-class/enum/extension/extension type) of a function that starts with static. We then don't have a name for "a top-level function or a static method", but it isn't so hard to spell that out when needed.

As I've mentioned in some other contexts, I'd prefer to use the word 'variable' to denote all language entities whose underlying semantics is determined by the behavior of storage: We can store a value "in" a variable, we can read it and get a value, and these operations do not have further side effects. The value won't change until some other action stores a new value at the same location. Some variables do not allow new values to be stored, so they always have the same value. Most variables have an associated getter and perhaps a setter, and they can only be accessed using that getter or setter. But we are generally very explicit about this distinction, so that shouldn't be a source of much confusion.

The word 'field' may be tempting to use with the meaning 'instance variable' because it's shorter, and rather common. I don't think that's a big problem if it is defined clearly as such. It would probably cover instance variables of classes, mixins, mixin classes, and enums, but perhaps not the unique instance variable of an extension type: That one is already known as the 'representation variable', and it's probably best to stick with that.

It would also be possible to use 'static field' and 'instance field' to cover both static variables and instance variables, but this means that much of the brevity of 'field' is destroyed.

[bwilkerson]

Beyond just the website, there's also a disconnect between the spec and tools too, diagnostics and their messages in particular. That's perhaps because Brian came from a Java world, where while "instance variable" and "static variable" (as well as "class variable") are used in the Java spec as well, I've mostly never seen those terms used in practice. It could also be a deliberate choice because "static field" and "instance field" are perhaps more familiar to users, which is what makes the solution to this problem extremely hard to me.

(I'm guessing that the quoted "instance variable" etc. were intended to be "instance field" etc., because there's only one place where "instance variable" is used, everywhere else we use "instance field" or "static field".)

I have read many language specifications (not just Java and Dart) and I can tell you that language specification authors use human language in a very formal and often stylized way. This leads to subtleties in the language of the specification. These subtleties are necessary because the specification has to be very precise to be of any value.

I've also dealt with users of programming languages for a long time and I can tell you that most users don't understand the subtleties of a given specification. They don't use precise terms when talking about a language, nor do they generally need the full precision of a specification in order to understand a concept.

These two facts have led me to believe that the worst thing we could do for our users is to stick to the strict language of the specification. We should, instead, use the commonly used terms that are users are using elsewhere. Sometimes those will be the same as the terms used in the spec, which is fine, but sometimes they won't be.

I used the term "field" because I believed that that's the term that users are most familiar / comfortable with. If that's not the case then we should absolutely not use it in our docs. But if that's what users call that particular concept, then we shouldn't use "variable" just because the spec does.

As an addition argument for this point of view, one of the premises for this issue is that using consistent terminology will make it easier for our users to search for information about a particular topic. If that's a goal (and I think it ought to be), then that's also a strong argument for being consistent with what the community uses. Remember, users search the internet, not just our documentation, so commonly used sites like stackoverflow are just as important for us to consider as any of our own documentation, maybe even more so.

[parlough]

I'm super glad you both responded, as I was planning to ping you both once I solidified my thoughts a bit more. I always appreciate both of your deep and thoughtful insights, they help me understand my own thoughts :D

We clearly all have the same goal, just with a few slightly different thoughts. It's still not clear to me the best path though, so I have a few questions and comments:

---

To @eernstg:

We could perhaps note that consistency makes familiarity easier to establish, because a limited amount of experience will cover the whole system pretty well.

As I've mentioned in some other contexts, I'd prefer to use the word 'variable' to denote all language entities whose underlying semantics is determined by the behavior of storage

That's what my thoughts keep going back to as well. Using the " variable" terms consistently bring the semantics of the term "variable" along with it. Most of my experience is helping absolute beginners learn programming and I do feel this could help them.

'static function' discussion

I guess I haven't really seen "static function" used often so I didn't think to bring it up, so thanks for bringing it to my attention. We only have two cases of it in the docs, and I think it makes sense to change those. My gut says that users would not see top-level functions as being included under the term, so it would be nice to change those references in the feature specifications as well :)

The word 'field' may be tempting to use with the meaning 'instance variable' because it's shorter...
It would also be possible to use 'static field' and 'instance field' to cover both static variables and instance variables, but

I have a question about this general body of text. Are you saying that "field" and "fields" would be fine to use (as long as they are defined), but should only be used when referencing instance variables?

---

To @bwilkerson:

(I'm guessing that the quoted "instance variable" etc. were intended to be "instance field" etc., because there's only one place where "instance variable" is used, everywhere else we use "instance field" or "static field".)

Ah sorry about the confusion, in those mentions I was referring to the fact the Java specification uses a mix of the <type> variable terms as well as <type> field in the specification, but everyone colloquially says field.

These two facts have led me to believe that the worst thing we could do for our users is to stick to the strict language of the specification.

I used the term "field" because I believed that that's the term that users are most familiar / comfortable with.

Oh, I completely agree with these statements and I completely understand why the "field" term is used instead in the diagnostics. I would have done so too. For familiarity and especially for the later point of view of "searchability" which is one of the largest issues we have with our language documentation. Another example of this, is that while I think "library variable" and "library function" are super nice because they bring along the semantics of specifically being within a "library", "top-level variable/function" is just too common to fight against.

In the end, I definitely don't think it's necessary to match the specification. My goal is that users should never even need to open it to learn everything they need to about Dart. Those that do need to read the spec, generally should have the ability to make the necessary distinctions. I'm just looking to the spec for options of consistency.

---

Loosely to both of you or anyone:

The reason I brought up the specification in this case, is because I am just trying to determine if the clarity/consistency/extra semantics of the "variable" terms it uses would be worth a little loss in familiarity? Or, if and how we should standardize to "field" terms, since we mostly introduce "instance/static variable" in the language tour currently and have for a long time. If that's the case, what rules should we follow to ensure clarity. Tooling for both sides (glossary with synonyms for searching, definition on hover, etc) can also be considered.

Brian is extremely right, "field" is the more familiar and common term, at least for those coming from other languages. On the other end, I think that for programming beginners, the explicit variable terms are better due to the extra meaning.

I do think if we have good answers to the following questions, I'd be more comfortable standardizing to field terminology:

• "Fields"/"a field" without a descriptor is sometimes used as a grouping term for both static and instance fields (It is also used for the properties of a record, but I think that's mostly a non-issue), but other times it is just referring to instance fields. Is this okay as the long as the context is clear? Can we make it more clear? More liberally add specifiers? Does that auto-translate well and can ESL/EAL developers understand it clearly?
  • Just to cherry-pick an example, the following text exists in a diagnostic doc: "If it’s desirable and possible to make the class a constant class (by making all of the fields of the class, including inherited fields, final), then add the keyword const to the constructor:".
    
    Maybe I'm wrong, but could a beginner mistake this as meaning the static fields declared within a class definition must be final too?
• Since the goal is consistency, if we use the field terms, should we even introduce the "instance variable" term, outside of a glossary entry and describing a field as being a specific type of variable associated with an instance?
• If we do decide to standardize to use "field" more in the language documentation, should the spec at least mention it as the often/commonly used term? It does this for library/top-level variables. It also already uses the term "field formal parameters" and "field initializers" so I think it may be beneficial to more formally introduce anyway.

---

That ended up being quite long, but I appreciate your thoughts. Hopefully we can get the website more consistent soon :D

[bwilkerson]

As I've mentioned in some other contexts, I'd prefer to use the word 'variable' to denote all language entities whose underlying semantics is determined by the behavior of storage

Using the " variable" terms consistently bring the semantics of the term "variable" along with it.

I don't think that users are confused when we use the term 'field', thinking "hm, I thought these were stored in memory, but since they're not called 'variables', maybe they aren't."

On the other hand, when I use the term 'local variable' I often have to clarify that that includes parameters because users don't think of parameters as variables. And from a spec perspective they aren't, right? Because they aren't stored in memory they're stored on the stack. And yet, the spec says that "Every formal parameter introduces a local variable into the formal parameter scope.". Maybe I'm misunderstanding what Erik wrote. I don't know, but either way I think users would find it awkward if we started talking about 'parameter variables'.

(Of course, to be fair, when I'm talking about 'local variables' I usually mean a variable whose scope is limited to a single function / method. And yes, I usually have to clarify that 'function' includes 'method' even though methods are just functions.)

English is messy, and I don't know that there's a way around it.

My gut says that users would not see top-level functions as being included under the term ["static function"], so it would be nice to change those references in the feature specifications as well :)

That kind of proves my point. From a specification perspective, everything said about a "static function" is true of top-level functions, so it's more precise and succinct to just say that once than to call them "top-level functions" and then have to repeat everything about them using both terms. We definitely shouldn't change the spec to conform to common terminology.

... I am just trying to determine if the clarity/consistency/extra semantics of the "variable" terms it uses would be worth a little loss in familiarity?

I think the answer is "no". We can clarify the semantics when we need to, but it's much better if the documentation is easy to read by depending on common usage.

Or, if and how we should standardize to "field" terms, since we mostly introduce "instance/static variable" in the language tour currently and have for a long time.

As I said before, IMO the language tour isn't the only documentation to consider. If it's the piece that's inconsistent with the larger body of documentation then it just needs to change. If anything I think users are likely to respond with "that's much easier to read, thanks for making the change."

Tooling for both sides (glossary with synonyms for searching, definition on hover, etc) can also be considered.

I like both of those ideas.

I think that for programming beginners, the explicit variable terms are better due to the extra meaning.

You might have more information here than I do, it's been a long time since I taught beginning programming classes at university, so the students have probably changed quite a bit. But I'm not convinced that either (a) the extra meaning will be obvious to beginning programmers (and hence not be as useful as it might seem) or (b) that using terms that are harder to look up in the larger community-written documentation is actually helpful even if they are more precise.

"Fields"/"a field" without a descriptor is sometimes used as a grouping term for both static and instance fields (It is also used for the properties of a record, but I think that's mostly a non-issue), but other times it is just referring to instance fields. Is this okay as the long as the context is clear? Can we make it more clear? More liberally add specifiers? Does that auto-translate well and can ESL/EAL developers understand it clearly?

Those are great questions for professional writers, which I'm not. But I don't think that switching to 'variable' changes the question at all. If anything it might just make it worse; at least 'field' only has two interesting subsets, while 'variable' has many more and hence opens the door for far more misunderstanding.

Maybe I'm wrong, but could a beginner mistake this as meaning the static fields declared within a class definition must be final too?

Yes, a beginner could absolutely make that mistake. (And there isn't a lot of context in that entry to help them not do so, so it probably ought to be improved.) Beginners often misunderstand. It might not be clear, for example, that static fields aren't inherited. In fact, there have been issues opened before asking why a subclass can't override an inherited static method.

I don't know the best way to write the documentation so that it doesn't confuse novice programmers while not being too verbose for experienced programmers. That's part of why this is a question for our doc team.

Since the goal is consistency, if we use the field terms, should we even introduce the "instance variable" term, outside of a glossary entry and describing a field as being a specific type of variable associated with an instance?

If the term "instance variable" is used by other languages, then we should definitely include it in the entry for 'field' because it will help users that know those other languages draw parallels to what they already know.

If we do decide to standardize to use "field" more in the language documentation, should the spec at least mention it as the often/commonly used term?

If the spec writers think that doing so would help readers understand the semantics being defined, then yes. If not, then no. But if you're asking whether the specification should be made more approachable for people who are trying to learn rather than implement the language, then I'd argue that it shouldn't be. It isn't intended to be an introduction to the language; that's the role of the language tour, tutorials, and even books written by community members.

[eernstg]

Thanks for the kind words, @parlough!

I looked around a bit and found this stackoverflow page about the terminology in Java. Several comments on that page do state something that means "a field is a special kind of variable", and they mention the connection between a variable and storage. They don't agree 100%, but I believe most of them say that "a field is an instance variable, at least unless it is explicitly described as static".

This Oracle glossary says that a field is "A data member of a class. Unless specified otherwise, a field is not static."

Perhaps this is completely irrelevant because it's specifically about Java, but it does illustrate that there is some prior art in that community for considering a field to be a kind of variable, biased in the direction of being an instance variable. It seems to come from an earlier terminology about records and similar constructs, and that reinforces the understanding that a field is a simple and low level concept (for instance, it doesn't include a getter/setter pair).

So perhaps it would be a good idea to use 'field' to mean instance variable, and 'static field' to mean static variable, and then include all kinds of variables in the glossary such that anyone who looks it up can at least see the connections.

As @bwilkerson mentioned, we do have some apparent confusion in this area in the specification documents as well, because we talk about 'parameters' and then specify that they "introduce" local variables into a specific scope. However, this is consistent with their behavior in that they are initialized at a call site based on actual arguments (which makes them different from plain local variables), but they work just like (initialized) local variables as soon as the beginning of the function body is reached.