10 ms·

I don't understand people recommending reading the source code to learn. Source codes can be really daunting because there are so many things going on. There ca

I don't understand people recommending reading the source code to learn. Source codes can be really daunting because there are so many things going on. There can also be "tricks" using advanced language features, which defeats the purpose if you're trying to learn as a first timer. Also, "read the source" is, at least to me, an admission that there is no valid documentation 90% of the time. Reading the source of a tool or a small to medium library is fine, it's not fine for large projects or projects you know nothing about. Incremental examples is where it's at. You should document a fonction/type/feature/whatever with a short example with basic operations and then a more involved example with good practices and potential caveats. I know this is a lot of work, I understand it can't be like that everywhere. This is not a dig at anyone's project or language, but "read the source code" comments always strike me as unhelpful.

iTokio 5y ago
Reading the source code is very helpful if you are an experimented programmer that already grasped the basics of the language. It helps you to see what are the idioms, what does optimized production code look like. Compare C++ and Go std lib and it’s easy to constate the difference in language goals that they have.
- stathibus 5y ago
  Reading the c++ stdlib source code is never a good idea.
  - FpUser 5y ago
    ROFL. Yup. When I look at application level codes those are nice. Looking at stdlib makes me want to walk away immediately.
  - einpoklum 5y ago
    It's not a fun experience to be sure, but: 1. It's useful when you want to check the exact under-the-hood behavior, to figure out side-effects or corner-case semantics. 2. After a good number of years, that code becomes less scary and more icky. Some of it remains kind of scary though... 3. Reading that code teaches you a lot about considerations you may be ignoring, especially your implicit platform-dependent assumptions. 4. Nitpick: There isn't any single C++ standard library source code, it's at least 3 popular ones (GCC's libstdc++, LLVM's libc++, and Microsoft's)
- pjmlp 5y ago
  Including the workarounds Go has gone through due to lack of generics, e.g. sync.Map.
ralphb 5y ago
In general I would agree, but (as multiple people pointed out) the zig standard library source code is very accessible.
- adito 5y ago
  I beg to disagree with you. I'm newbie and I still found that zig standard library still daunting to read. When people said it's very accessible, I'm curious what people mean by that? What makes it very accessible?
  - dnautics 5y ago
    I can't put my finger on it. I love ruby, but often times digging deeper into Ruby source code, I would hit a point where I would think, "oh God, I give up, this is magic". Comparing it to elixir, my daily driver, is like night and day. Usually I can figure out what is happening (there are a few places, like Phoenix Routes and Ecto Query Builders where I have gotten stimied). Zig is even better - especially at the stdlib level
  - heavenlyblue 5y ago
    > I'm newbie and I still found that zig standard library still daunting to read If you're a newbie, why are you learning an experimental language?
    - all2 5y ago
      Even noobs can love languages. I'm a noob at compilers and I routinely beat my head against implementation. I do this, not because I will succeed, but because I enjoy the challenge.
  - ralphb 5y ago
    I am also a zig newbie. Since zig is a relatively simple language, I've found it easy enough to read and understand what is going on in the zig standard library, even if I don't understand the particular details of some language syntax. Of course experience and background is going to play in here. The zig standard library does the following to help me: - Logical, straightforward code, no magic incantations - Well named variables and functions - Comments - Folder structure is easy to navigate - Easy to find on github - not hidden away Obviously your mileage may vary.
styluss 5y ago
It makes less sense when the source code uses idioms that aren't recommended for other code
dnautics 5y ago
It's important to consider that for zig at this stage, "not having valid documentation" is expected. At some point not having valid docs will become considered to be unacceptable. Forcing people to read the code puts pressure on the code to be clean. Not writing docs against an unstable API is a strategy to make it freer for the authors to change the API, possibly in sweeping breaking ways (for example allocgate).
- the_duke 5y ago
  I also tried out Zig a while ago and was frustrated by the lack of good learning materials. Zig is 6 years old. Rust had much better documentation at this stage of development. To be fair though: Rust also had corporate backing and a larger fan base contributing to the book and std docs.
  - dnautics 5y ago
    Seriously, comparing by timeline like that is an unfair comparison. You should probably kick a few dollars into the zig foundation as penance for having made it publically. ;)
    - Zababa 5y ago
      > comparing by time spent is an unfair comparison Yes, and language competition is unfair. As a user, I don't care that Zig is more "cost/time effective" than Rust or Java, I care about the end result. The end result, right now, is a worse documentation than lots of other languages. That doesn't mean that the people behind Zig are bad or anything like that. That just means that when choosing between X and Zig, Zig's documentation (and lack of such documentation) will influence my choice. I'm not sure why you would not compare by timeline, as this is probably the best predictor of where a language will be in the next years, which is important data as well.
      - dnautics 5y ago
        If you're going to compare that way (and I contend you shouldn't) at least normalize by programmer hours, or take into account growth.
Comevius 5y ago
The Zig std source code is easy to navigate, and it won't be documented until it is stabilized. I prefer to look up the source code either way, examples and the documentation can only get you so far.
- rightbyte 5y ago
  > it won't be documented until it is stabilized Heh ... Good one.
_vvhw 5y ago
> "read the source code" comments always strike me as unhelpful. I can understand why people would recommend reading the source code of projects like Redis or SQLite (and here Zig's std lib) to learn, simply because the code quality is so high. It's also not like anyone is proposing that there will be no documentation when Zig turns 1.0 (as if high quality documentation and code quality were mutually exclusive!) simply that Zig is not YET at that stage [1]. There's much to love about Zig, and it's always a good time to be reading code, and all the more so while it's growing and shaping because you end up with a deeper knowledge and understanding of what makes a great project great. [1] Personally, I do find the language documentation to be pretty much excellent and the IRC and Discord helpful—hey, you might even bump into Mitchell Hashimoto also asking questions there. It's the std lib that's a little less, but again, that's in flux and files like `std/mem.zig` are enough of a pleasure to read and learn from. Zig's definitely a swell worth paddling.
hnlmorg 5y ago
It also depends on the individual. While I value documentation, I find source so much easy to understand than several paragraphs in English describing how to use language features. But I know others much prefer reading docs over code.
jlarocco 5y ago
> This is not a dig at anyone's project or language, but "read the source code" comments always strike me as unhelpful. I agree, reading the source is a good way to learn more once a person already know the language. It can be great to help track down a bug, or learn about an obscure corner case in a function, or see more advanced idioms in use, but it's a pretty terrible and unfriendly way to learn a language in the first place.
forrestthewoods 5y ago
Blog author here! I read the source quite a few times. Almost every language has a dynamic array of some sort. They all do the same thing. They all have slightly different names. push / push_back / add / append. size / length / len / count. If you don't already know the name of a function then finding it is in a sea of text is very difficult and not fun. Zig ArrayList: https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig https://github.com/ziglang/zig/blob/master/lib/std/array_lis... C++ Vector: https://en.cppreference.com/w/cpp/container/vector https://en.cppreference.com/w/cpp/container/vector Rust Vec: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html Sometimes I just want to see a list of functions. I can skim a list of 40 functions in seconds. Scrolling 800 lines of code and trying to pick out every single function takes much longer and is much more error prone.
- mst 5y ago
  When I find myself in such a suboptimal situation, I tend to fall back to grep '^ *pub fn' <file> or equivalent for the language in question. A smarter approach would probably be a code folding plugin for my editor, but I tend to keep my editing environment deliberately stupid so I can spend my cognitive complexity budget elsewhere. (this is not to downplay your annoyance, just it seems worth mentioning that stupid problems often have stupid workarounds and I have lots of practice at being stupid ;)

iTokio 5y ago

Reading the source code is very helpful if you are an experimented programmer that already grasped the basics of the language. It helps you to see what are the idioms, what does optimized production code look like. Compare C++ and Go std lib and it’s easy to constate the difference in language goals that they have.

stathibus 5y ago
Reading the c++ stdlib source code is never a good idea.
- FpUser 5y ago
  ROFL. Yup. When I look at application level codes those are nice. Looking at stdlib makes me want to walk away immediately.
- einpoklum 5y ago
  It's not a fun experience to be sure, but: 1. It's useful when you want to check the exact under-the-hood behavior, to figure out side-effects or corner-case semantics. 2. After a good number of years, that code becomes less scary and more icky. Some of it remains kind of scary though... 3. Reading that code teaches you a lot about considerations you may be ignoring, especially your implicit platform-dependent assumptions. 4. Nitpick: There isn't any single C++ standard library source code, it's at least 3 popular ones (GCC's libstdc++, LLVM's libc++, and Microsoft's)
pjmlp 5y ago
Including the workarounds Go has gone through due to lack of generics, e.g. sync.Map.

ralphb 5y ago

In general I would agree, but (as multiple people pointed out) the zig standard library source code is very accessible.

adito 5y ago
I beg to disagree with you. I'm newbie and I still found that zig standard library still daunting to read. When people said it's very accessible, I'm curious what people mean by that? What makes it very accessible?
- dnautics 5y ago
  I can't put my finger on it. I love ruby, but often times digging deeper into Ruby source code, I would hit a point where I would think, "oh God, I give up, this is magic". Comparing it to elixir, my daily driver, is like night and day. Usually I can figure out what is happening (there are a few places, like Phoenix Routes and Ecto Query Builders where I have gotten stimied). Zig is even better - especially at the stdlib level
- heavenlyblue 5y ago
  > I'm newbie and I still found that zig standard library still daunting to read If you're a newbie, why are you learning an experimental language?
  - all2 5y ago
    Even noobs can love languages. I'm a noob at compilers and I routinely beat my head against implementation. I do this, not because I will succeed, but because I enjoy the challenge.
- ralphb 5y ago
  I am also a zig newbie. Since zig is a relatively simple language, I've found it easy enough to read and understand what is going on in the zig standard library, even if I don't understand the particular details of some language syntax. Of course experience and background is going to play in here. The zig standard library does the following to help me: - Logical, straightforward code, no magic incantations - Well named variables and functions - Comments - Folder structure is easy to navigate - Easy to find on github - not hidden away Obviously your mileage may vary.

styluss 5y ago

It makes less sense when the source code uses idioms that aren't recommended for other code

dnautics 5y ago

It's important to consider that for zig at this stage, "not having valid documentation" is expected. At some point not having valid docs will become considered to be unacceptable. Forcing people to read the code puts pressure on the code to be clean. Not writing docs against an unstable API is a strategy to make it freer for the authors to change the API, possibly in sweeping breaking ways (for example allocgate).

the_duke 5y ago
I also tried out Zig a while ago and was frustrated by the lack of good learning materials. Zig is 6 years old. Rust had much better documentation at this stage of development. To be fair though: Rust also had corporate backing and a larger fan base contributing to the book and std docs.
- dnautics 5y ago
  Seriously, comparing by timeline like that is an unfair comparison. You should probably kick a few dollars into the zig foundation as penance for having made it publically. ;)
  - Zababa 5y ago
    > comparing by time spent is an unfair comparison Yes, and language competition is unfair. As a user, I don't care that Zig is more "cost/time effective" than Rust or Java, I care about the end result. The end result, right now, is a worse documentation than lots of other languages. That doesn't mean that the people behind Zig are bad or anything like that. That just means that when choosing between X and Zig, Zig's documentation (and lack of such documentation) will influence my choice. I'm not sure why you would not compare by timeline, as this is probably the best predictor of where a language will be in the next years, which is important data as well.
    - dnautics 5y ago
      If you're going to compare that way (and I contend you shouldn't) at least normalize by programmer hours, or take into account growth.

Comevius 5y ago

The Zig std source code is easy to navigate, and it won't be documented until it is stabilized. I prefer to look up the source code either way, examples and the documentation can only get you so far.

rightbyte 5y ago
> it won't be documented until it is stabilized Heh ... Good one.

_vvhw 5y ago

> "read the source code" comments always strike me as unhelpful. I can understand why people would recommend reading the source code of projects like Redis or SQLite (and here Zig's std lib) to learn, simply because the code quality is so high. It's also not like anyone is proposing that there will be no documentation when Zig turns 1.0 (as if high quality documentation and code quality were mutually exclusive!) simply that Zig is not YET at that stage [1]. There's much to love about Zig, and it's always a good time to be reading code, and all the more so while it's growing and shaping because you end up with a deeper knowledge and understanding of what makes a great project great. [1] Personally, I do find the language documentation to be pretty much excellent and the IRC and Discord helpful—hey, you might even bump into Mitchell Hashimoto also asking questions there. It's the std lib that's a little less, but again, that's in flux and files like `std/mem.zig` are enough of a pleasure to read and learn from. Zig's definitely a swell worth paddling.

hnlmorg 5y ago

It also depends on the individual. While I value documentation, I find source so much easy to understand than several paragraphs in English describing how to use language features. But I know others much prefer reading docs over code.

jlarocco 5y ago

> This is not a dig at anyone's project or language, but "read the source code" comments always strike me as unhelpful. I agree, reading the source is a good way to learn more once a person already know the language. It can be great to help track down a bug, or learn about an obscure corner case in a function, or see more advanced idioms in use, but it's a pretty terrible and unfriendly way to learn a language in the first place.

forrestthewoods 5y ago

Blog author here! I read the source quite a few times. Almost every language has a dynamic array of some sort. They all do the same thing. They all have slightly different names. push / push_back / add / append. size / length / len / count. If you don't already know the name of a function then finding it is in a sea of text is very difficult and not fun. Zig ArrayList: https://github.com/ziglang/zig/blob/master/lib/std/array_list.zig https://github.com/ziglang/zig/blob/master/lib/std/array_lis... C++ Vector: https://en.cppreference.com/w/cpp/container/vector https://en.cppreference.com/w/cpp/container/vector Rust Vec: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html https://doc.rust-lang.org/stable/std/vec/struct.Vec.html Sometimes I just want to see a list of functions. I can skim a list of 40 functions in seconds. Scrolling 800 lines of code and trying to pick out every single function takes much longer and is much more error prone.

mst 5y ago
When I find myself in such a suboptimal situation, I tend to fall back to grep '^ *pub fn' <file> or equivalent for the language in question. A smarter approach would probably be a code folding plugin for my editor, but I tend to keep my editing environment deliberately stupid so I can spend my cognitive complexity budget elsewhere. (this is not to downplay your annoyance, just it seems worth mentioning that stupid problems often have stupid workarounds and I have lots of practice at being stupid ;)