Added workshop that introduces trainees to the basics of TypeScript #343
Conversation
…and typechecking"
✅ Deploy Preview for cyf-workshops canceled.
|
✅ Deploy Preview for cyf-workshop ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Poonam-raj
left a comment
Poonam-raj
left a comment
There was a problem hiding this comment.
The purpose of this workshop is clearly filling a gap in knowledge. I've come at this review in the mindset of a fresh volunteer or trainee.
Based on the material around types it could be plausible that some students have never engaged with the type syntax properly before and with this workshop being an introduction it feels apt to cover the foundations so a few of my suggestions encourage breaking down the basic syntax.
A few other suggestions touch on phrasing. And there's a bit more about how the Learning Objectives connect with the workshop material.
Few general suggestions:
- Re: phrasing - mainly my aim was to bring the facts to the front and the context second. Looking to be as clear in language as possible.
- Generally more instruction is needed in how this workshop is executed, to enable volunteers and trainees to know exactly what their role in each section will be.
Please let me know if anything is unclear or if anything actually doesn't fit the intention for the workshop.
Thanks!
| - Breakout into groups of about 3 to 5 trainees. | ||
| - Make sure you have access to the [exercise repository](https://github.com/CodeYourFuture/CYF-Workshops/tree/main/introduction-to-typescript). | ||
| - Clone it to a local project. | ||
| - Follow the instructions in `README.md` to setup the project and run the exercise. |
There was a problem hiding this comment.
Is this one clone per group or everyone in the group clones the repo?
Worth highlighting team working here, that we are working as a group to complete the exercise on one project if that's the intention.
If this is a group exercise on one clones repo it might be worth considering making this a pairing problem where all students have to engage with what's going on.
There was a problem hiding this comment.
I was thinking for one person to screen share while the others drive. The person screen sharing will of course need to clone the repo but I think it best that everyone clone the repo so that people can swap roles as they go through the exercises.
Do you think a group of 3 to 5 trainees is too big for these exercises? I'm worried about there not being enough volunteers to see to every group if a group is 2 trainees.
There was a problem hiding this comment.
5 feels large, 3 would be the max really but risks the third person not engaging much if there isn't enough time to swap three times.
I would also make it more explicit that we want the team working off the same fork of the repo - I would love to embed the practice of pairing on the same fork to keep git skills up
…ore detail. - Included more tips for volunteers on how to run this workshop.
There was a problem hiding this comment.
The aim of this exercise is to apply what they learnt during the prior DAY_PLAN_WORKSHOP.md content. The solution is quite straightforward and is essentially answered within DAY_PLAN_WORKSHOP.md.
I don't expect this exercise to take more than a few minutes for trainees but it does make their first hands-on experience with TypeScript manageable.
There was a problem hiding this comment.
The simplest solution is to just have the function return an object that is of type User
There was a problem hiding this comment.
The solution to this exercise is to ensure the return type of this function is number, and params a and b are both of type number
There was a problem hiding this comment.
The simplest solution is to specify a: number and b: number, which causes the return type to be inferred as number
There was a problem hiding this comment.
Specifying an incorrect type will cause exercise2.test.ts to fail a test
There was a problem hiding this comment.
This is a fairly open ended exercise. The problem is that a try catch block will always treat the error as type unknown, which isn't helpful and is prone to type errors. The simplest solution is to treat an error as any type, which is commonly done. This is a flawed but valid approach to handling errors. Trainees should be encouraged to handle errors with more nuance.
A better and also common solution is to use type coercion. We know the error type will be Error given throw new Error("Failure!") is very predictable. This is a better solution than the anytype but is still flawed. If thetry` block were more complicated, we might have room for other unexpected error types.
My preferred solution is to validate they type of error and then use error in a predictable manner.
Trainees might come with other solutions. It will be up to volunteers to critique the trainees approaches and offer feedback. I'm assuming trainees will be googling and/or asking AI for suggestions. My bet is that the above approaches will be the most common solutions online.
| "extends": "./tsconfig.json", | ||
| "include": ["src/tests/exercise2.test.ts", "src/exercise2.ts"], | ||
| "comments": { | ||
| "file": "This file exists to ensure that vitest's temperamental compile-time typechecking only runs against exercise 2. Without this config, other files will be typechecked when running exercise 2." |
There was a problem hiding this comment.
JSON files do not support comments. This is my preferred approach for commenting in JSON files. I've left this here to hopefully aid any future developer who might decide to edit this workshop.
Vitest's compile-time typechecking is used in exercise 2. This is an experimental vitest feature. I found it quite finicky to configure, especially given I needed it to only run on specific files. It has a tendency to typecheck everything it can see, similar to tsc which it leans on.
There was a problem hiding this comment.
If you're curious, here is a handy tutorial on compile-time testing with vitest from the developer who added it to vitest.
https://www.youtube.com/watch?v=S-8kEhYpqqA
Poonam-raj
left a comment
Poonam-raj
left a comment
There was a problem hiding this comment.
Thanks for addressing all my points, it reads so much clearer for both students and volunteers. I added one response to the group of 3-5 comment, mainly noting if we need to be explicit about working on the same fork.
The other big question on my mind is whether there's so much new material here that this should be split between prep material (lines 1 - 179ish) and a workshop (the rest of the day plan). Unsure if this is a future iteration of the workshop and not something we edit now. Will ask on the thread
Intention
This workshop is intended for trainees with some basic understanding of typed languages but with no experience with TypeScript. It will require volunteers having familiarity with TypeScript, but strong familiarity with another typed language might be sufficient.
This workshop was originally built for and used within SDC Sprint 4 (Types and typechecking) as a day plan workshop. This PR includes a
DAY_PLAN_WORKSHOP.mdfile that could be transposed into the day plan if some minor changes are made to match the markdown of the day plans.If you'd like more context on how this workshop came about, there is an extensive Slack thread discussing it.
Things to keep in mind while reviewing this
Is the write up sensible?
This is the 2nd iteration (3rd of 4th in my head) of this workshop. Please keep an eye out for text that feels out of place. I've proof read everything but I might have left bits that made more sense in previous iterations.
Does this code run well?
I'd appreciate reviewers running and completing the exercises themselves if possible. The config became a bit messy due to different exercises requiring different testing patterns. I think the tests are giving helpful feedback to trainees but there might be edge cases where unexpected errors come through.
Exercise 2 utilises experimental vitest features to test at compile time. This exercise is the most likely to result in unexpected or unhelpful behaviour.
Future improvements and my thoughts on further TypeScript exposure
This workshop aimed to automate as much of the grading of exercises as possible. I used vitest to accomplish this, which proved quite tricky since vitest is mostly intended for testing at runtime. This means it is difficult to ask a trainee to build a
type SomeTypeand then automate a test againstSomeType.If another means of testing code at compile time can be found, it might be viable to follow the approach of this workshop. Otherwise it might be best to take a different approach for further TypeScript work. Having volunteers more involved in the grading and feedback, for example how
exercise3.tsoperates, might be viable.My recommendation would be to have further learning of TypeScript be a byproduct and not the main focus. This could be accomplished by having JavaScript backlog work keep its current content but rather be written in TypeScript.
How I've seen others teach TypeScript
Total TypeScript has an excellent and short beginner course, which was the main inspiration behind these exercises. I'm guessing they encountered the same problems as me, hence their later exercises also not leaning on automated tests.
W3Schools takes a different approach by focusing on knowledge of TypeScript. Their exercises are not run within an IDE and tend to be very short code snippets.
