The Subtyping and Variance chapter is confusing
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 2.3k
- Forks
- 325
- PR merge metrics
- No merged PRs in 30d
Description
Today in the Rust community discord we had a discussion about variance and the nomicon chapter discussing it (starting here), and how it's generally confusing and is something that just doesn't "click" for a lot of people (myself included).
First impression
I'll start off by summarizing my (and others') impressions as we read the chapter.
Subtyping is a relationship between types that allows statically typed languages to be a bit more flexible and permissive.
Uh, ok. This tells nothing about what subtyping is supposed to mean. (it's much later that this is actually explained)
Subtyping in Rust is a bit different from subtyping in other languages.
Well I don't know what "subtyping in other languages" is, either.
To keep things simple, this section will consider a small extension to the Rust language....
...So here's our simple extension, Objective Rust
Seems kinda random how we got here. Why are we introducing a new language? I'm interested in what variance is in Rust and why I should care about it. This is anything but simple.
<lots of cats, dogs and animals>
At this point the article has completely lost me.
Constructive feedback
There are some things that could be done better:
- Show locked doors before we show keys. We probably want to introduce basic subtyping (you can pass
&'static Footofn bar<'a>(&'a Foo)), then show an issue with doing that (adapt the "meowing dogs" example to lifetimes) and then introduce variance to deal with this. - explain "is a subtype of" in terms of "is as useful as and more"
- Possibly make readers read less cats and dogs before explaining it again in terms of lifetimes.
- I think the author(s) underestimate how unintuitive cats, dogs and animals analogies actually are (see also the linked article below). Please don't use inheritance-y analogies.
- The article dumps a lot of "we will explain this later" on the reader. Please don't underestimate how exhausting and confusing this is. For example there's an enormous distance between when variance is first mentioned and when it is explained.
Finally I would recommend you to read https://viralinstruction.com/posts/defense/. The author's frustration with teaching classes and inheritance is how I feel w/r to subtyping and variance.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Nomicon’s Subtyping and Variance chapter and review the discussion linked in the issue for the reported teaching problems. Identify a revised structure that explains lifetime subtyping and variance directly, reduces the cats-and-dogs analogy, and avoids deferred explanations. Done means the chapter is clearer to readers without prior familiarity with the topic.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100