Create a glossary of terms used by Carbon

[sidney13]

It was suggested in the 2020-07-01 Carbon meeting that there should be a glossary of term that are used when discussing Carbon to ensure that all parties has a common understanding.

[josh11b]

Some terms that I'd like to see covered, that come up in more than one doc:

• template-const vs. generic-const (the distinction between constant whose value may be used as part of type checking vs. being used symbolically at type checking time but constant at code generation time).
• parameters vs. arguments (covered in my most recent revision of the pattern-matching proposal).

[manshreck]

I'd like to have this issue be crowdsourced for terms that people either need clarification on, or expect need to be defined. I'll go through the docs and add terms as well, but this additional set of terms could be useful.

So if you run across a term that you think needs to be defined, simply note it in this issue.

[jonmeow]

@manshreck Do you have a terminology doc that you've been drafting? I'd like to introduce terminology as part of a proposal, and I'm leaning towards the idea that the best way that the best way to do that is to put them into a glossary doc as part of the proposal.

[manshreck]

@jonmeow I don't have a draft at this time. I agree that having a change to the glossary doc as part of the pull request would be best. In the meantime, maybe just add those terms here as TODOs?

[josh11b]

FYI, I did create a terminology doc for generics, which can be seen here: https://github.com/josh11b/carbon-lang/blob/generics-docs/docs/design/generics/terminology.md Don't be too surprised if I make changes to it though, it hasn't been submitted yet.

[jonmeow]

@manshreck The reason I'm looking to start the terminology doc is because I want to use terminology in the proposal that people might understand, but it'd be helpful to fill in. e.g., 'package' is the full foo.bar.baz path to an entity in Java; it's a unit of distribution in Python. My proposal uses 'package' in Carbon, and the conflict in terminology cross-language begs a definition. Further, the precise definition may also change during RFC, as it already has during drafting.

I was considering generating docs/guides/glossary.md; e.g., https://github.com/carbon-language/carbon-lang/pull/107/files#diff-77f8f46ccc1fd10ce6a8ca0def9c6fa9

[jonmeow]

@josh11b I think the terminology doc may make sense to stick with generics as it's laying broad strokes for the design, but I'm really trying to stick to tight definitions.

[manshreck]

My inclination is that we should have one, canonical terminology document. We can restrict the terminology to a specific domain perhaps by adding tags (e.g. "generic") to entries and somehow generating a restricted set of glossary terms e.g. terminology.md?tags=generics.

In the meantime, if you want to have local terminology documents, that's probably OK, bit I would want to refactor those and canonicalize them at some point.

[jonmeow]

The difference I'd draw with Josh's terminology doc is that it's actually drawing comparisons between possible generics approaches, several of which Carbon will not pursue. That's different from what I'd expect from a glossary, where I'd expect an alphabetized list of definitions that's easy to scan for things I don't understand.

[github-actions[bot]]

We triage inactive PRs and issues in order to make it easier to find active work. If this issue should remain active or becomes active again, please comment or remove the inactive label. The long term label can also be added for issues which are expected to take time. This issue is labeled inactive because the last activity was over 90 days ago.

[chandlerc]

Reviving this as I just found I wanted such a thing again reviewing a proposal.

There are a growing number of important terms we use in the design of Carbon that would be good to document. Notably, many of these have specific nuance that we leverage in Carbon and likely need a place to clarify.

I'd suggest that this should be a top-level document in docs/glossary.md as I think it will end up pertaining to the design and many, many other things.

For areas where there is an especially important difference to draw between possible terminologies like Jon points out we have in generics, I would suggest that the terms actually used in Carbon get a brief summary entry in the Carbon glossary with a link to into the more nuanced terminology document. It is a small amount of duplication, but I think we should optimize a bit for helping folks find the information they are looking for more easily and by looking in fewer places.

[chandlerc]

Concrete examples of terms I'd love to see here that have come up in recent discussions and reviews:

• "parameters" and "arguments" -- notably, the distinction between them
• "receiver" or "implicit object parameter/argument" or ... -- whatever feeds self.
• "witness", "witness table" ...
• possibly "monomorphization" and "instantiation" -- here I've suggested these as useful terms to capture a specific distinction that otherwise we have no real terminology to reference

I'm sure there are more that I'm missing.

Some of these bring up an additional advantage to a top-level document -- it gives us a good place to talk about these terms broadly from the Carbon centric perspective, whereas a terminology document for some specific area of the design may instead want to narrowly talk about the terminology as it occurs in that domain, how it is used, and even how the terms are used outside of Carbon in order to establish background context. But the main glossary can instead both cut to the chase of precisely how Carbon uses things and be more broad to cover specific aspects of how we use terms across different parts of Carbon. So it can include specific nuance for implementation contexts or API design or ....