book

book copied to clipboard

URL to the section(s) of the book with this problem

• 2nd edition, p. 186, 3rd paragraph.
• https://doc.rust-lang.org/book/ch10-01-syntax.html

Description of the problem

You write 'Note that this code won’t compile yet, but we’ll fix it later in this chapter', but this fix is not provided. After listing 10-5, there is a confusing explanation about the compilation error but the reader doesn't have the necessary knowledge yet since trait bounds are only introduced in the next section.

Latest repository files

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • "10-5"
  • "trait bound"
  • "10.1"
• I have checked the latest main branch (rev. 8fa6b85, 13 April 2023) to see if this has already been fixed, in these files:
  • book-main/listings/ch10-generic-types-traits-and-lifetimes/*.rs
  • book-main/src/{ch10-01-syntax.md, ch10-02-traits.md, ch10-03-lifetime-syntax.md}
• It wasn't possible to build the book because of an error when compiling mdbook, so I didn't check on the website built from the latest revision.

Other related information

In the ch10-02-traits.md file, this seems to suggest that the promised fix would be introduced there:

<!-- Old headings. Do not remove or links may break. -->
<a id="fixing-the-largest-function-with-trait-bounds"></a>

It's the only file with that ID, I didn't find any reference to it.

Suggested fixes

By decreasing preference:

(1) I would reorder the chapter to avoid that sort of confusion. Even if the fix was provided later, leaving the reader with a pending unexplained problem defeats the purpose of the example. The readers build their knowledge by reading the theory and a set of illustrative, working examples that reinforce the learning. Starting with an example that doesn't work can only generate confusion.

Why not introduce the generic trait and the trait bound directly?

The different cases of generic, struct, enum, and functions, are particular cases that can be listed later instead of squeezing them before explaining the more fundamental concept of trait bounds.

(2) Another solution would be to avoid the error by directly showing the right code with the trait bound, and telling that it's explained in the next section.

(3) Another solution would be to introduce the fix in section 2, but it's a poor fix.

Agreed that we could improve this a bit, but the fix is actually immediately below! “Later in this chapter” is actually the misleading bit, because the text supplies (via compiler error message and instructions about following it) the solution:

By following the help text's suggestion, we restrict the types valid for T to only those that implement PartialOrd and this example will compile, because the standard library implements PartialOrd on both i32 and char.

What I think we need to do here is change from “later in this chapter” to something more immediate-seeming. Given both you and the commenter at #3718 found this confusing, we might want to make the fix (“no, really, do what the compiler error tells you to do!”) slighly more explicit, too.

The problem, if you do that, is that you are using a concept that hasn't been introduced yet. Hence my suggestion of reordering the chapters, or avoiding to need a trait implementation in the generic example (which is perfectly possible). Don't show an error that requires extra knowledge to fix - it's not didactic. Or show the fix later, once that knowledge is there, but it wouldn't be ideal. You can still show a generic with a trait bound later.

It's really a recurrent issue in that book, due to the order concepts are presented.

I also found this confusing and it was strange to never see the function being completed. That is especially apparent to those following the book while coding at the same time. Maybe that snippet can be used a segue into the next section?