Make writing generics more "scary"

[SeanTAllen]

We cover (briefly) generics in the tutorial.

Using generics that others have written is generally straightforward in Pony but writing generics can be very hard.

As it says on the website.

Generics and references capabilities are the hardest things to get a handle on while learning Pony so don’t get frustrated. It’s not just you. We all go through this. During the video, you’ll hear one of our core team members, Sean T. Allen, commenting at numerous points that he was sort of following everything but not all of it. Sean now has a strong grasp on all the concepts. It takes time.

We should make sure people come away from the generics section of the tutorial with an understanding that using should be straightforward but that writing them is "Pony on hard mode".

[rhagenson]

Writing Pony generics is definitely advanced Pony, not intermediate Pony as I thought at one point.

What are you suggesting here? An upfront warning that generics are more difficult than they first appear, or perhaps a final reminder that generics take longer to learn in Pony than other "similar" languages?

[SeanTAllen]

I think we want people to come away with:

• using shouldn't be an issuing.
• writing is advanced mode and difficulty level will be higher than other languages because of the unfamiliarity w reference capabilities.

writing generics is probably the hardest thing a pony program will do in terms of interacting with the type system.

[rhagenson]

Understood.

To whoever wants to handle this issue, I am willing to help in writing and/or review. Making something more "scary" is a unique way to contribute so I welcome an outside perspective on the matter.

Edit: Clarify what I mean by help

[schnittchen]

Where does the difficulty lie? Getting the reference capabilities (including ephemeral^ or alias! types) right so that the generic is actually useful beyond the first use case at hand?

[rhagenson]

Ephemeral and alias types are part of the difficulty, yes. A solution to this issue would make that difficulty clear as well as at least preview one way where generics without refcaps are made more complicated (and unsafe) with refcaps added. As refcaps do not exist at runtime all safety must be guaranteed at compile time.

Do you have thoughts on how to approach this section, @schnittchen?

[schnittchen]

For the time being this would be far beyond my capabilities. An idea might be to point into the stdlib and give the reader a hint about some subtleties.

[shaedrich]

Writing Pony generics is definitely advanced Pony, not intermediate Pony as I thought at one point.

Would it make sense to indicate the knowledge level with some kind of label right at the top of the page, or even display a list there, including the topics, you need to understand in order to consider working with this topic?

[jemc]

Would it make sense to indicate the knowledge level with some kind of label right at the top of the page, or even display a list there, including the topics, you need to understand in order to consider working with this topic?

We discussed in the Pony sync today.

We think that this kind of generalized system would be somewhat heavy to initially sketch out the content for, and maintain. And the amount of value we get out of that may be fairly low, compared to just mentioning an appropriate comment in the prose.