TS McNamara (18) [Avatar] Offline
#1
Absolutely delighted to receive any feedback on the introductory chapter. It's had quite a large number of revisions as the table of contents has been revised. Please let me know if there is any content that should be culled or expanded.
abattisti (3) [Avatar] Offline
#2
Typos in Chapter 1
Don't know if this is the right place, but looks like there is a typo in the code sample in Section 1.1.1 (Safety):

fn for_each(v: &Vec<T>) {
     for item in 0..v.len() {
        work(v[things]);
     }
}


Line 3: "things" should probably be "item" .

In the code sample in section 1.1.3 (Control) if the integer 40 is protected by a Mutex, it is not possible to print it via "{}" (i.e. Display is not implemented for Arc<Mutex<_>>) so I guess this:

...
let d = Arc::new(Mutex::new(40));

println!("a: {}, b: {}, c: {}, d: {}", a, b, c, d);
...


should be either replaced with:

...
let d = Arc::new(40);
println!("a: {}, b: {}, c: {}, d: {}", a, b, c, d);
...


or :

...
let d = Arc::new(Mutex::new(40));

println!("a: {}, b: {}, c: {}, d: {:?}", a, b, c, d);
...


Best,
Alex
TS McNamara (18) [Avatar] Offline
#3
Typos in Chapter 1
abattisti wrote:Don't know if this is the right place, but...


Thanks very much of these corrections, Alex! I'll make sure that they're included in the next version of the MEAP. This is the perfect place for them. Thanks once again smilie
267849 (17) [Avatar] Offline
#4
"Yet the differences are sufficiently different to minimize issues..." What?

Like most natural language statements on second derivatives, this is completely inscrutable to me, how similar would the differences have to be to maximize issues?
267849 (17) [Avatar] Offline
#5
I hope the dependence on nightly will go away for the published version, the ecosystem instability caused by everything depending on some version of nightly seems to be a favorite argument among detractors. And there is half a sentence missing in "Execute rustup install nightly . This enables extra features to ."
267849 (17) [Avatar] Offline
#6
Some of the numbered notes to listing 1.1. end with a period, some don't.
267849 (17) [Avatar] Offline
#7
Section "1.1.1 Safety": I think the flow of the argument is a bit lacking here. There is no really convicing logical or rhetorical step from the compiler inserting integer overflow checks to "fearless concurrency". I know where it comes from, but it appears quite unmotivated in the actual context of the argument as presented. And it isn't helped by the fact that "imploding" is not the most common metaphor to describe the behavior of programs.

It is also not quite clear what the "similar principle" is similar to, to the fearless concurrency, the degrees of freedom or to the additional runtime checks in debug mode?

There is again something missing in "0..v.len() returns an iterator from the"
267849 (17) [Avatar] Offline
#8
Section 1.1.2 "Ergonomics":

"the preceding code would fail to compiler"

And I think this is an unconvincing example with a rather unhelpful error message. For comparision, common C compilers with sensible options will pinpoint the actual issue exactly and suggest appropriate fixes:

$ clang -Wall -Werror assign.c 
assign.c:6:9: error: using the result of an assignment as a condition without
      parentheses [-Werror,-Wparentheses]
  if (a = 10) {
      ~~^~~~
assign.c:6:9: note: place parentheses around the assignment to silence this
      warning
  if (a = 10) {
        ^
      (     )
assign.c:6:9: note: use '==' to turn this assignment into an equality comparison
  if (a = 10) {
        ^
        ==
1 error generated.


"mismatched types" can't hold a candle to this from an ergonomics standpoint. One could make a point that it is nice that the compiler doesn't need a special case rule for this error, but that makes it easier for the authors and not the users of the compiler.
267849 (17) [Avatar] Offline
#9
Section 1.1.3 "Control":

The section ends with a reference to "these three principles", which are probably safety/ergonomics/control, but that phrase is followed by three more sentences written in the form of a maxim that are not directly following from the preceeding text. So it is tempting to read the period after "principles" as a colon and the following three sentences as the list of principles referred to by "these three", ending up with two different sets of threee principles guiding the language. And the differences between the sets are different enough to be slightly confusing.
267849 (17) [Avatar] Offline
#10
Section 1.2 "Rust's big features":

With my deviant reading of the end on 1.1.3 this is the third set of three fundamental things in three pages, this may be overusing the rhetorical figure. Part of it repeats things that have already been said (but then they say that repetition is the mother of all learning, so that may be OK), and part of it may only be convincing (or even understandable) to people who already don't like Python for some very specific technical reasons.
267849 (17) [Avatar] Offline
#11
Section 1.3.2:

"Programs it won't start"
267849 (17) [Avatar] Offline
#12
Section 1.3.3:

"Rust’s referencing system are->is implemented as"

It it also not clear what referencing here refers to, it is most likely the reference counted boxed objects (Rc/Arc), but in the context of rust the word is also used for references (&) to values. So maybe "Rust's reference counted values are implemented as...". And is this even useful knowledge at this part of the journey?

The part starting with "There are design decisions" doesn't completely fit under "Size of the Language", instead it repeats parts of the other "Downsides" subsections (and 1.3.3 itself).
267849 (17) [Avatar] Offline
#13
Section 1.3.4:

"Rust is likely to have helped" - shouldn't there be a "would" somewhere in there?

"The issue lies between lines 11 & 13." The listing does not show line numbers, will this be different in the final version?
267849 (17) [Avatar] Offline
#14
1.4.4:

macOS -> iOS

267849 (17) [Avatar] Offline
#15
1.6.2:

The last four paragraphs read a bit like disconnected factoids, while I think that they were meant to be a coherent argument like this:

Systems languages tend to be powerful, but unwieldy [missing: for example by requiring explicit memory management and careful attention to the types of values. Rust tries to provide the power without this unwieldiness]. Some languages get around the memory management problems by having a GC, but rust solves this differently. And while rust is statically typed, the compiler is smart enough to take away much of the pain.

And I'd qualify it as most of the convenience of a garbage collector, at the end of the day the borrow checker is a pedantic nitpicker which most garbage colletors are not.
267849 (17) [Avatar] Offline
#16
1.1.3 Control:

The code doesn't compile:
$ rustc control.rs 
error[E0277]: the trait bound `std::sync::Mutex<{integer}>: std::fmt::Display` is not satisfied
  --> control.rs:12:51
   |
12 |   println!("a: {}, b: {}, c: {}, d: {}", a, b, c, d);
   |                                                   ^ `std::sync::Mutex<{integer}>` cannot be formatted with the default formatter; try using `:?` instead if you are using a format string
   |
   = help: the trait `std::fmt::Display` is not implemented for `std::sync::Mutex<{integer}>`
   = note: required because of the requirements on the impl of `std::fmt::Display` for `std::sync::Arc<std::sync::Mutex<{integer}>>`
   = note: required by `std::fmt::Display::fmt`

error: aborting due to previous error

$ rustc --version
rustc 1.20.0 (f3d6973f4 2017-08-27)
$
TS McNamara (18) [Avatar] Offline
#17
267849 wrote:The code doesn't compile:
println!("a: {}, b: {}, c: {}, d: {}", a, b, c, d);


Try
println!("a: {}, b: {}, c: {}, d: {:?}", a, b, c, d);
.

This makes use of Debug, rather than Display but should get you past the compiler. Apologies for the error. Niggles like that are annoying!
TS McNamara (18) [Avatar] Offline
#18
267849 wrote:Systems languages tend to be powerful, but unwieldy [missing: for example by requiring explicit memory management and careful attention to the types of values. Rust tries to provide the power without this unwieldiness]. Some languages get around the memory management problems by having a GC, but rust solves this differently. And while rust is statically typed, the compiler is smart enough to take away much of the pain.


This is an extremely helpful suggestion. I certainly want to improve chapter 1. Its a bit of a Frankenstein at the moment. Quite a lot has been pulled together from other writing. Will work hard to smooth things out.

267849 wrote:And I'd qualify it as most of the convenience of a garbage collector, at the end of the day the borrow checker is a pedantic nitpicker which most garbage colletors are not.


Fair point!
TS McNamara (18) [Avatar] Offline
#19
267849 wrote:macOS -> iOS


Controversial point. From memory, my technical ed actually asked me to remove iOS in favour of macOS. I also had ObjectiveC in there, rather than the current Swift. I believe macOS is the current name though and will better serve future readers.
TS McNamara (18) [Avatar] Offline
#20
267849 wrote:"Rust is likely to have helped" - shouldn't there be a "would" somewhere in there?


Perhaps this is a New Zealand-ism? It sounds natural to my ears, but perhaps a more conventional sentence structure would be more appropriate.

"The issue lies between lines 11 & 13." The listing does not show line numbers, will this be different in the final version?


Yes! Urgh, I thought that I had fixed all of those. Thanks very much for reporting the issue.
TS McNamara (18) [Avatar] Offline
#21
267849 wrote:Section 1.3.3:

"Rust’s referencing system are->is implemented as"

It it also not clear what referencing here refers to, it is most likely the reference counted boxed objects (Rc/Arc), but in the context of rust the word is also used for references (&) to values. So maybe "Rust's reference counted values are implemented as...". And is this even useful knowledge at this part of the journey?

The part starting with "There are design decisions" doesn't completely fit under "Size of the Language", instead it repeats parts of the other "Downsides" subsections (and 1.3.3 itself).


Agree that the language and structure is fairly muddled in this section. Some editorial surgery will be required to enhance the flow and comprehensibility. Thanks for pointing this out. It's surprisingly obvious when someone quotes your text, but very difficult when one is in the middle of writing a large block of text.
TS McNamara (18) [Avatar] Offline
#22
267849 wrote:"the preceding code would fail to compiler"

And I think this is an unconvincing example with a rather unhelpful error message. For comparision, common C compilers with sensible options will pinpoint the actual issue exactly and suggest appropriate fixes: ...


This is a fair point. I muddled around for a few hours attempting to think of an example that was concise yet compelling. At the end of the day though, I certainly recall the frustration of using the assignment operator when I meant to be comparing values when learning to code. If I get any ideas over the next few months, I will certainly inject them into the prose!

"mismatched types" can't hold a candle to this from an ergonomics standpoint. One could make a point that it is nice that the compiler doesn't need a special case rule for this error, but that makes it easier for the authors and not the users of the compiler.


I also agree that the error message could be improved.. I wonder if assignment is being used within an expression that will be evaluated by a logical test whether something more direct could be said, "Perhaps you meant == rather than =?"
TS McNamara (18) [Avatar] Offline
#23
267849 wrote:I hope the dependence on nightly will go away for the published version, the ecosystem instability caused by everything depending on some version of nightly seems to be a favorite argument among detractors. And there is half a sentence missing in "Execute rustup install nightly . This enables extra features to ."


First of all, apologies for the missing half sentence.

Yes, I am hopeful that nightlies won't be required by the time the book goes to print. It's a difficult choice for me to make. Do I pin to a version, say 1.20, and then make the book seem to be over a year old by the time it comes out? At this stage, I'll go for nightly and reconsider when the bulk of the work is done.