Why is the error handling chapter of the second edition of TRPL so sparse?


#1

Folks, why is the error handling chapter of the second edition of TRPL so sparse? Have the techniques mentioned in the first edition been replaced by something better? More specifically the second edition does not say anything about working with functions returning different error types in the same caller function.

First edition: https://doc.rust-lang.org/book/error-handling.html
Second edition: http://rust-lang.github.io/book/second-edition/ch09-00-error-handling.html


#2

@steveklabnik is probably the best person to ping about this question.


#3

How do I do that?


#4

This page lists a #rust-docs IRC channel that’s probably a good place to start.


#5

Thanks!


#6

Isn’t the 2nd Edition marked as draft? So my best guess - they are still working on it.


#7

Maybe, but it seems they have advanced this chapter to the “Nostarch - copy editing” phase: https://github.com/rust-lang/book/projects/1. Would you copy edit something half done?


#8

The first edition was written by @burntsushi in a blog post, and was so good we pulled it into the book.

However, with the second edition, we’re trying to make a better book. That means a few different things in many ways, but as for this chapter specifically:

  1. It’s long. This is good, but it’s also bad: this isn’t a book about error handling, it’s a book about the language itself. Error handling is important, but it’s one of many important things.
  2. It’s written in @burntsushi’s voice, not @carols10cents’ and mine. Which was fine for the first edition, which came with a lot of different stuff we shoved in there. But with the second edition, we have higher standards. That means we’d end up having to re-write this chapter anyway.
  3. Some of this info doesn’t fit into the primary goal of the book, which is to teach people how to use the language. The advice for library authors stuff is wonderful, but doesn’t really fit in with the mission of the book. The deeper dive into traits in the stdlib would be wonderful in the stdlib, but doesn’t really fit in with the book.

TL;DR: the blog post is great, but isn’t right for the book anymore. Does that all make sense?


#9

Just to clarify that my and @steveklabnik 's voice is not inherently better than @BurntSushi’s voice, that’s not the higher standard-- the higher standard is having one consistent voice across the book :slight_smile: :heart: @BurntSushi!


#10

@steveklabnik thanks for your reply, much appreciated!

Your goal for the book is commendable. But please do take a moment and consider if you are really helping people learn the language by leaving out such details? The book does a stellar job at many places. In particular I loved the chapters on ownership, references and lifetimes. But I can’t help but wonder if it is a little sparse on the details in some other areas (notably error handling, how single ownership and immutability cover for each other in making the language safe and maybe some other areas)?

And since posting this question I have (re)discovered two additional resources the Rust reference manual and the Rustonomicon. I think they cover advanced topics in much greater detail. But they do not cover many practical issues of concern which a beginner must know to be effective in rust either.

Isn’t it better to delay publication and fix things now rather than receive the same feedback after publication? I think it is still not too late for a course correction.


#11

Yes, exactly 1000%, thanks for clarifying.


#12

It is impossible for the book to contain every last detail. Everyone has their own particular issue they care about for something that should be covered in more depth, or in less depth, or should be added, or be removed. This is the biggest responsibility an author has: judging what goes into a work, and what gets left out. It is incredibly difficult, and so it is likely we’ll make some kind of mis-step here :smile: Such is life.

FWIW, you’re the only person who has brought this up so far. Which doesn’t mean you’re alone, mind you, but this particular thing isn’t something we’ve heard often. In fact, some people found the size and length of the previous version intimidating, and prefer the new one! That’s one reason why I want to see more Rust blogs; there’s no reason that both can’t coexist, and in fact, they do!


#13

Fair enough! Thanks again for taking the time out and writing a response.


#14

Something that is frustrating to me in both the first and second edition is that I feel like there is not enough information on how to define your own errors and compose them. Notably, it appears this is completely absent from the second edition. Handling errors is explained well, but it seems like the second edition expects people to get by with io::Result, expect, and panic. I’d expect some discussion of defining an error enum, and implementing From, Display, etc.


#15

Also, if we did that, we’d probably delay publication forever. It’s never going to be perfect.


#16

I understand how this is frustrating. One problem we have with this with the book is that IMO the Best Practice currently is to use either quick-error or error-chain to do these sorts of things. However, we are deliberately trying to minimize the number of crates that we mention. So far, we’re only mentioning crates that are either in rust-lang, in rust-lang-nursery, or will be there by the time that the book is published, and will have a 1.0 version by the time the book is published, so that the crates we recommend in the book will have stability and maintenance guarantees. We want the book to stay relevant for as long as possible given that crates evolve more quickly than the language, and we also want to avoid playing favorites in the ecosystem.

I’d love to see someone create a comprehensive resource about all the ways for library authors to define and use errors that DOES go into detail about using crates, though!


#17

I too have found the error handling chapter a little lighter than I would like to see. To often error handling seems to get put off or not talked about then everyone wonders why new programmers’ code lack any when they’ve been taught by everyone that it’s not important or maybe really hard so it’s just better not to do it. I understand about the concern that the old text was a bit long and as you said in a different voice but it’s really much to important topic to not have more written about it IMHO anyway.