Open blueglyph opened 1 year ago
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 implementPartialOrd
and this example will compile, because the standard library implementsPartialOrd
on bothi32
andchar
.
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?
URL to the section(s) of the book with this problem
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
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}
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: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.