Chapter 10.1: Missing trait bound fix for error in listing 10-5

[blueglyph]

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.

[chriskrycho]

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.

[blueglyph]

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.

[zkkv]

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?

[km274]

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.

I found my way to this issue because I noted that as @chriskrycho mentioned the solution in explained in text, but I was hoping to see the code too.

Since the syntax for the solution hasn't been introduced yet, it would be helpful to see it in code and not just in text. This would align with the pattern used throughout the book of presenting some code that doesn't compile, discussing why it doesn't compile, and then presenting the modified code that will both compile and produce the expected behavior.

I know that the others here have already given a few suggestions for how to make things more clear, but I have my own suggestion. It wouldn't require changing the structure of the chapter:

1. Change the "later in this chapter" to "soon" (I agree that "later in the chapter" is a bit confusing)
2. Add the working code between the paragraph that explains the solution in text and the next "In Struct Definitions" section

I'm happy to open a PR if the maintainers like this solution (or even if the discussion converges on a different solution).

Edit: I went back through this section of the book carefully, and I now see that the syntax I wanted an example of is already included in the compiler error message shown directly after listing 10-5:

1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

So I no longer think a code example needs to be added, though I do see opportunities to tweak the wording that I feel would make things clearer. I will see about opening a small PR to put my thoughts out for review.