Notes on Course Material

[coastalwhite]

Hey, I decided to look through the Course Material and have some questions and comments which hopefully can help the course forward. Overal I agree with most of the structure.

Target Audience

What is the actual target audience of the course? Is it targeting first year's students or students later in their university life? My current impression is that is trying to target both, which is fine but is probably quite a lot more difficult.

To deal with these differences in the audience experience, it may be interesting to provide a block with most programming syntax and semantics sections with 4-5 tabs. This should try to explain it which the readers specific context and give the professors good resources depending on the context at the university.

One tab should explain the concept as if the reader has no programming experience, others should explain it as if the reader is coming from a specific programming language. As far as I know the most common languages to learn first at university are C, Python, Java and JavaScript. We can compare basic concepts to how they are in those languages.

A1

The A1 module mostly seems fine to me. One of the parts I maybe agree a bit less with is the Move Semantics. Personally, I would take this chance to explain the rationale for the Borrow Checker and also explain the Drop semantics (not the Drop trait). I feel like most people would agree this is one of the major mechanisms that sets rust apart from other programming languages and having people familiar with it seems like something you want to do as soon as possible. Later you could link back onto this and explain things in a little more detail. Meanwhile students may connect some dots and detect some patterns themselves.

Some others small things:

• rustc --explain is really useful
• Some exercises with theoretical questions about the borrow checker

A2

This is probably the module I have the most comments about.

• Personnally, I would explain lib vs bin and the module system in this section as I feel like they are both extremely vital to looking at any form of rust code.
• I would move opt-levels and LTO to module B. These things are extremely domain specific and just distract from the important basics. Same for cross-compilation.
• SemVer is extremely widely used in Rust. It should at least be mentioned here, I reckon.
• Mention the rustonomicon in module F and not here.
• Just provide a list of commonly used crates (serde, rand, libc, nix, syn, quote, proc_macro(2)) and explain why not everything is in the std

A3

• Maybe do mention into & from with the casting but don't explain them detailed as of yet. Just plant the seed that there might be a method that is used in most situations.
• Maybe add a part about const contexts.
• Small part on macro_rules! since these are widely used
• Leave out union here and explain that in F with the unsafe and FFI parts

B

• Part on normal headers in documentation. Already partly included in Rust API guidelines

C

• Mention Rayon
• Maybe reference the book by Mara Bos on the topic

D

• Explain the different memory models that can be used while programming rust. This is mostly from the Jon Gjengset video on unsafe rust. I do think this is quite important but may take a long time to explain properly. Maybe there are some external resources that do this already and we can link to those.

E

• Part on WebAssembly

A0

Maybe, it is an idea to have an A0 module that is specifically for universities trying to use Rust as their intro to programming class. This may be out of the scope of this project, let me know.

This module can explain some of the more general and basic programming concepts. This could cover motivations for items and introduce working code without to much explanation as to what they are. Providing a lot of space for the student to infer their own patterns. I need to do more research into how other courses do this, but right now some of the items I think it should introduce are:

• Variables
  • Numbers (unsigned, signed, floating point)
  • Chars and strings
  • Groups of structures
• Control Flow
• Loops
• Functions
• Input / Output
• Compartimentilization
• Examples of common domains
  • Web
  • Systems
  • Embedded
• Common problems
  • max / min
  • serialisation
  • parsing
  • sorting

Thoughts

I think it will be very difficult to balance time and what to explain where.

I would love to help writing parts of this course. I would love to hear your opinions on these items and if you agree with some, I can send a PR with those changes. Also, if you would like me to look into some specifics let me know. If you would like to have me start writing on some topic, also let me know. Again, would love to help.

[hdoordt]

Hi @coastalwhite, thanks for your input!

First of all, I think it'd be great to introduce a module for students that don't have much programming experience, like you suggested. For now, the course is aimed at students with 'intermediary c++ knowledge', by which we mean that they should know about pointers and their dangers, heap allocations and freeing variables, stuff like that. This could surely be introduced in an A0 module, which may even serve as an alternative for parts of A1.

As for your other input: thanks! I'll be going through them more thoroughly shortly, and will write a more elaborate reaction once I've gotten to that.

[coastalwhite]

Hi @hdoordt,

Sorry for not coming back to you. Just finishing up some of my last exams of my life 😃.
I will look at contributing in some writing hopefully somewhere after the coming week. I had 2 more notes that are
important to cover:

1. Common hurdles when learning Rust
2. Reference Implementation

Common hurdles when learning Rust

There are a couple of common hurdles that people face:

• &str and String (and Cow<str>, and Vec<u8> and bstr and ...). What they mean and when to use them.
• The Module System can be (sub)titled as "Multi-file Rust projects" or "Including other source files" or something in that general trend. I have seen too many people struggle to understand this part of Rust. I know this topic is mentioned in the Course Material. Still, for slides and course material, it may be a good idea to improve searchability explicitly mention the goal of the Module System. It also lets people instantly draw some connections to other languages they may know.
• Everything Object-Oriented Programming (OOP) related.

When I think of some other topics that are common hurdles, I will add them to this list. Additionally, these are just from my experience of teaching other people Rust or seeing people in my environment learn Rust. I can also ask on Reddit to crowdsource some of these Common Hurdles.

Reference Implementation

One other thing, that should be explicitly covered and is quite systematically under covered in most Rust resources, is what references actually are. Namely, the 3 different types of references.

1. &T where T is Sized is just a pointer
2. &T where T is not Sized is a fat pointer (pointer + size / element count)
3. &dyn Trait is a pointer with a pointer to a virtual method table (vtable)

Especially in the later modules, this becomes significant. So, this may be added to module F when talking about the Type Memory Layout or in G when talking about the FFI support.

I hope this helps a bit more. Again, I will hopefully start writing about some of these parts as well next week. I see the @rnijveld is doing (sorry to pull you in to the issue). Would it be okay for me to start writing on A4? I will try to match the writing style of that PR a bit.

[hdoordt]

Hij @coastalwhite, thanks for your offer on writing a module. We have already divided the work on the modules that are currently defined and will be used for STU over several people and in fact I'm currently working on A4.

I will add you as reviewer for A4, if you're ok with that. If you want to start writing modules, I suggest you define modules that are not yet covered, like your suggested A0 module in order to make the material suitable for other audiences

[hdoordt]

@coastalwhite So I finally had some time to go through your feedback. Thanks again! So here goes:

Hey, I decided to look through the Course Material and have some questions and comments which hopefully can help the course forward. Overal I agree with most of the structure.

Target Audience

What is the actual target audience of the course? Is it targeting first year's students or students later in their university life? My current impression is that is trying to target both, which is fine but is probably quite a lot more difficult.

Good question. This, I feel, warrants a small fix to the README, where it's stated that the course is targeting students with 'intermediate c++ knowledge'. That's vague, but to make it more exact: it's targeted at the first set of students this course will be taught to. However, this is just the initial target audience, and I'd like to think about how to make the course suitable for other people as well. One group that comes to mind is people that have no programming experience whatsoever, and that's a tough one. We could do that, by adding more modules that may be taught before A1 or even instead of A1-A4. Below, you suggest adding an A0 module, and I think that could work.

To deal with these differences in the audience experience, it may be interesting to provide a block with most programming syntax and semantics sections with 4-5 tabs. This should try to explain it which the readers specific context and give the professors good resources depending on the context at the university.
One tab should explain the concept as if the reader has no programming experience, others should explain it as if the reader is coming from a specific programming language. As far as I know the most common languages to learn first at university are C, Python, Java and JavaScript. We can compare basic concepts to how they are in those languages.

This seems like a great idea to me, and would benefit lots of different students. Dedactively, it's very effective to couple Rust concepts to anaglogues from other languages. I do feel this is a stretch goal for now, but I'd love to think a bit more about how this could take shape.

A1

The A1 module mostly seems fine to me. One of the parts I maybe agree a bit less with is the Move Semantics. Personally, I would take this chance to explain the rationale for the Borrow Checker and also explain the Drop semantics (not the Drop trait). I feel like most people would agree this is one of the major mechanisms that sets rust apart from other programming languages and having people familiar with it seems like something you want to do as soon as possible. Later you could link back onto this and explain things in a little more detail. Meanwhile students may connect some dots and detect some patterns themselves.

Some others small things:

• rustc --explain is really useful

• Some exercises with theoretical questions about the borrow checker

This is a bit of a tough one. I should first not that as of right now, A1 does not contain a part on 'why Rust' yet, but that's in the pipeline. Motivating the use of the borrow checker in Rust would definately fit here (explaining what problems it solves from a high level), but I feel it'd be too much to go into the technical details of it here. This module should not become too big and I think move semantics is already pretty big of a subject as it is, and the borrow checker explanation depends on it. Hence we moved the content about references and the borrow checker to A3, which is currently in the works.

A2

This is probably the module I have the most comments about.

• Personnally, I would explain lib vs bin and the module system in this section as I feel like they are both extremely vital to looking at any form of rust code.

I've been thinking of moving that part to A2 myself too. We may end up doing that later on. @rnijveld, how do you feel about this?

• I would move opt-levels and LTO to module B. These things are extremely domain specific and just distract from the important basics. Same for cross-compilation.

As of right now, I think we may even want to skip opt-levels and LTO. Maybe move them to module F, if relevant there.

• SemVer is extremely widely used in Rust. It should at least be mentioned here, I reckon.

I think that would be more fitting in module B, but I'm not convinced we shouldn't just have students look it up during an exercise

• Mention the rustonomicon in module F and not here.

I think it's OK to just mention its excistence here for anyone that likes to go that extra mile

• Just provide a list of commonly used crates (serde, rand, libc, nix, syn, quote, proc_macro(2)) and explain why not everything is in the std

That would also be most fitting in an exercise, I reckon

A3

• Maybe do mention into & from with the casting but don't explain them detailed as of yet. Just plant the seed that there might be a method that is used in most situations.

Just planting the seed should be enough here. If time allows, we may do that. However, introducing Into and From along with the other traits in A4 seems fine to me

• Maybe add a part about const contexts.

We'll leave that out for now or maybe move it to an exercise.

• Small part on macro_rules! since these are widely used

They are, but I'm torn as I wouldn't want to make the module too big and I feel macro_rules earns a thourough explanation. Maybe create a separate module on macros somewhere in the future?

• Leave out union here and explain that in F with the unsafe and FFI parts

I agree. We may even leave unions out completely

B

• Part on normal headers in documentation. Already partly included in Rust API guidelines

What do you mean by normal headers here?

C

• Mention Rayon

Good one!

• Maybe reference the book by Mara Bos on the topic

That book is a great reference. @folkertdev is currently going through it and is planning on using it in this module.

D

• Explain the different memory models that can be used while programming rust. This is mostly from the Jon Gjengset video on unsafe rust. I do think this is quite important but may take a long time to explain properly. Maybe there are some external resources that do this already and we can link to those.

I don't feel explaining different memory models in a module about design patterns is fitting though. Even still, memory models are a broad topic and it would warrant a separate module

E

• Part on WebAssembly

I think we may even want to make that a separate module in the future, but we could surely mention WA's excistence

A0

[...]

I think this would be very valuable, but at the same time quite challenging. For the short term, this isn't a high priority for me, but I'd love to think along with you and others on how we could set this up.

Thoughts

I think it will be very difficult to balance time and what to explain where.

That is challenging indeed, and it's why I'm very happy with your input! :)

[folkertdev]

yes, rayon is definitely part of my plan (although... it makes things so simple, all my examples are just map-reduce :) )

Mara's book is truly excellent. I do struggle a bit with how much and what parts to put into a course like this. Current ideas

• work with (scoped) threads on a high level
• something about blocking (with a spin loop and by using OS primitives)
• Mutex in rust contains its data (why this is needed and why this is nice)
• sending some stuff between (scoped?) threads, going into the Send and Sync traits
• I'm conflicted about async. it must be mentioned, for some things it is intuitive ("wait for many things at once, efficiently") , but it adds a lot of complexity

[hdoordt]

@coastalwhite Just wanted to express my thanks again for providing us with feedback. We're currently at a new phase of Rust 101 (and this issue is getting a bit outdated), so I'm closing it.