Phrasing of expect message(s)

[aksh1618]

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • expect
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • https://github.com/rust-lang/book/blob/main/listings/ch03-common-programming-concepts/no-listing-15-invalid-array-access/src/main.rs

URL to the section(s) of the book with this problem: https://rust-book.cs.brown.edu/ch03-02-data-types.html

Description of the problem: I'm fairly new to rust, although I've been trying to get into learning and using it at times. Today I was looking into Nix, and stumbled onto Amos' series on Building a Rust service with Nix. One of my favorite parts of the rust code in the series was the usage of expect, such as here:

    let _guard = sentry::init((
        std::env::var("SENTRY_DSN").expect("$SENTRY_DSN must be set"),
        sentry::ClientOptions {
            release: sentry::release_name!(),
            ..Default::default()
        },
    ));

This series motivated me to finally continue my long deferred rust learning journey. As it had been some time since I last read the first few sections of the book, I decided to start over, skimming the parts I had already covered. But while skimming through the third chapter, this usage of expect caught my eye:

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

This was in complete contrast to the way I saw expect being used in the series, the way which had hit me like a breeze of fresh air and wooed me into exploring rusty meadows. And thus I had to come here. I feel like messages expressed in this manner would have felt more in place were the method called something like orElsePanic or expectOrPanic. However for a method named expect, it feels more natural (to me) for the message to state the expectation, and not what went wrong.

Suggested fix:

I understand that this could just be a consequence of my unfamiliarity with the language, but still I'm interested in knowing what others think about this, and how their brain parses this usage of expect. If others also feel the same way as me, maybe the way the messages are worded in invocations of expect throughout the book could be updated. For instance, for the above snippet from Chapter 3, it could be rephrased form "Index entered was not a number" to "Index entered should be a number".

I did consider if this was too small a thing to point out, but being the first contact for many for this method as well as for the rust language, I would expect (no pun intended) small things like this in The Book to play an important role in showcasing the pragmatism of the rust language and how working with it can feel so pleasantly natural. However I apologize if it is indeed (too small a thing) or if this is not the right place for a discussion such as this.

[StefanSalewski]

However for a method named expect, it feels more natural (to me) for the message to state the expectation, and not what went wrong.

Fine observation. I read the official Rust book myself in the the last weeks, and the use of the expect() method was one of the strangest things of Rust that I discovered. For my feeling as a non native English speaker, as expect() is used most of the time with a string parameter reporting an error, its name should have been something like "on_error()". It is often used counter-intuitive. Others found that as well, see https://stackoverflow.com/questions/66362625/why-is-rusts-expect-called-expect

The API docs specify how it should be used, see https://doc.rust-lang.org/std/result/enum.Result.html#method.expect

Hint: If you’re having trouble remembering how to phrase expect error messages remember to focus on the word “should” as in “env variable should be set by blah” or “the given binary should be available and executable by the current user”.

But often it is used without this "should".

Some people may regard this as a minor, unimportant issue, but it causes friction for new users. So a note about the issues in the book would help.

[aksh1618]

The API docs specify how it should be used, see https://doc.rust-lang.org/std/result/enum.Result.html#method.expect

Hint: If you’re having trouble remembering how to phrase expect error messages remember to focus on the word “should” as in “env variable should be set by blah” or “the given binary should be available and executable by the current user”.

Thanks for linking the documentation, always good to have a hunch validated! Now I feel even more strongly that the examples in The Book should be changed to reflect this style, as it has been explicitly specified in the docs. And I agree with the suggestion of including a note as well (and/or probably even a link to the documentation, it will be a good example of how the Rust docs can be really helpful!)