Feedback
I read your introduction series, here’s some feedback.
00-getting-started
No problems here.
01-hello-world
There are no hidden conversions, no implicit type coercions, […]
This is sort of saying the same thing twice, and there is a short list of them here, so it’s not completely true either:
https://odin-lang.org/docs/overview/#implicit-type-conversions
I do understand wanting to keep it simple and not mentioning it, but it’s probably better for the reader to at least be aware that although the amount of implicit type conversions is low, it’s not completely 0 either.
The same is true for the ‘explicit type conversions’ section.
Here age becomes an int .
It might also be nice to mention the untyped/existential types here, to explain why age becomes an int there (because a literal is an untyped constant that implicitly converts to a specific type if none are given at a particular point).
The full form for a typed constant is name : type : value . With inference, name :: value is sufficient.
This is a simplification I think is actually good, because the details for explicitly typed constants would be too overwhelming for beginners.
02-data-and-memory-management
In my opinion, this chapter focuses a bit too much on the context allocators.
Then again, it’s for beginners in Odin, and not necessarily about learning memory management strategies, so I don’t have any actionable criticisms on the general structure.
The first is a filing cabinet — structured, long-term storage for data that needs to survive beyond a single task. You are responsible for clearing it out when you are done. This is context.allocator . Pair every allocation with a defer delete() placed immediately below it, so that cleanup is always visible next to creation.
There’s a bit of a contradiction here, where it’s both long-term storage, yet it should always be deleted in the same scope. You do allude to lifetimes here and there, but it might be good to explain the concept more thoroughly.
There are also some slightly incorrect mentions about how fixed arrays work:
// 1. Fixed array — stored directly in CPU local memory
A fixed-size array is an array whose size is known at compile-time. They are stored contiguously on the stack and do not grow or shrink.
- Fixed arrays have a compile-time size and live in stack memory.
It’s not just you saying it, but I always think it sounds a bit weird when people say fixed arrays live on the stack, because they are just value types like structs, and yet nobody says ‘structs live on the stack’. Perhaps it would help to compare fixed arrays to structs in some way to explain what they are?
I don’t envy your position in this chapter, as I don’t really see how to explain this stuff to beginners without going down many rabbit holes to explain lifetimes, computer architecture, and memory management. This would take way too long, and wouldn’t fit this series very well.
03-control-flow
I suppose you could mention in the ‘Exhaustive Switch Statements’ section that the default case functionality is actually orthogonal to #partial, as an enum’s value could be corrupted and thus not match any named value.
Every fallible call follows the same shape
I wouldn’t say it’s every fallible call, one should try to handle errors sooner rather than later, if possible (without extreme duplication).
. Hopefully it’ll be something that complements the existing Odin book.