Chapter 3.1. Variables and Mutability. Revised Sentence

[YS-McGee]

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • until either it itself is shadowed
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • src/ch03-01-variables-and-mutability.md

URL to the section(s) of the book with this problem: https://github.com/rust-lang/book/blob/main/src/ch03-01-variables-and-mutability.md?plain=1#L130

Description of the problem: The English problem is a bit of redundancy and a lack of parallel structure, which can affect clarity.

Suggested fix (Corrected Sentence): "In effect, the second variable overshadows the first, meaning any uses of the variable name will refer to the second variable until it is either shadowed again or the scope ends."

Current Sentence: "In effect, the second variable overshadows the first, taking any uses of the variable name to itself until either it itself is shadowed or the scope ends."

[StefanSalewski]

Thanks for reporting. I read that section one year ago, and as a non native speaker, I had to read it twice. This section is one more example of how good AI can write prose:

Original:

Shadowing

As you saw in the guessing game tutorial in Chapter 2, you can declare a new variable with the same name as a previous variable. Rustaceans say that the first variable is shadowed by the second, which means that the second variable is what the compiler will see when you use the name of the variable. In effect, the second variable overshadows the first, taking any uses of the variable name to itself until either it itself is shadowed or the scope ends. We can shadow a variable by using the same variable’s name and repeating the use of the let keyword as follows:

GPT-4o

Shadowing

As demonstrated in the guessing game tutorial in Chapter 2, you can declare a new variable with the same name as an existing one. This is known as shadowing. When a variable is shadowed, the new declaration supersedes the previous one, meaning the compiler will only recognize the most recent version of the variable within its scope. Essentially, the new variable "shadows" the old one, redirecting all subsequent uses of the variable name to itself. Shadowing can be done by redeclaring the variable with the let keyword, as shown below:

At least myself as a non native English speaker can read and understand the latter text easier. And I think the meaning is the same.

Reference: https://chatgpt.com/share/66f13030-9cdc-8006-8711-86598c3e709b

[chriskrycho]

This is interesting – I didn’t write the original sentence so I have no attachment to it, but I don’t think either of the suggested revisions are clearer. The GPT suggestion is okay prose, but definitely not an improvement in my book, just different and worse in some spots; the use of “overshadows” instead of repeating “shadows” again in the original helps clarify what “shadow” even means in context! I am going to go ahead and close this. Glad you were able to understand it in the end!

[StefanSalewski]

but definitely not an improvement

I could ask AI to explain to you all the details -- but it is so obvious, that I can do it manually:

The term "As you saw" is problematic in various kinds. It is seldom used in technical writing, and obviously is not fully correct, as the reader might have skipped that chapter. "As demonstrated" is actually an often used term in technical writing.

In the original "Rustaceans say" is used improperly, as the concept of shadowing is common in computer science and not specific to Rust users.

The phrase "repeating the use of the let keyword" in the original was actually the reason I had to read that section twice a year ago as a Rust beginner.

Compared to the original, the AI text is perfect technical English -- the content is easy to understand and fully correct.

I read the whole official Rust book a year ago. In my opinion it has many issues, I reported a few, as others did as well. But it became obvious that the original authors are not that much interested in fixes. That is OK, the book is just good enough as an extended introductory tutorial to the Rust language. I read later "Programming Rust" of Mr. Blandy, which is a much more detailed Rust book with relatively few issues -- I found only a few dozen in all the 700 pages.

Indeed it is fascinating how good AI can now write English prose, especially for technical documentation. AI is very good at rewriting. Unfortunately, when it is asked to write something on its own, it sometimes missed something, or in very rare cases writes nonsense, so carefully human proofreading is necessary.

Sorry for my bad English -- this post has not been corrected by AI :-)

[StefanSalewski]

Just for fun, I just picked a sentence from the book which I highlighted for a reason in October last year, and asked AI:

https://chatgpt.com/share/66f67961-2e50-8006-b0df-590a4de8d5ee

GPT-4 is still my favorite tool, but I think that others like open-source Llama or Claude are already close.

[chriskrycho]

@StefanSalewski, I want to take this opportunity to make it clear that your enthusiasm for improvements to the book is very welcome, but:

1. Suggestions that we adopt language from ChatGPT or similar systems will 100% be ignored, not only for stylistic or philosophical reasons (though I certainly have some opinions on those fronts) but also because the legal status of anything generated by those tools is extremely murky at best. If you find it helpful personally, use it to your heart’s content—but we will not be using it in these contexts whatsoever.

2. Matters of style are not matters of correctness, however strongly we might feel about a given style. I personally have quite a few differences with the “house style” preferred by our publisher, NoStarch, but it is their house style, so we use it. Likewise, there are quite a few ways in which my own “voice” as an author differs significantly from the “voice” of the book (independent of the style guide)—you can see my website for plenty of examples of how I write, and you will see that it is not the same as the way I wrote for the new async chapter. Regardless, I am quite happy to tailor my writing for the book to the existing style of the book.

If and when you find something unclear or confusing, please do keep reporting it! However, please do try to distinguish style opinions and preferences from matters of correctness and be aware that we will not make changes on things we judge to be matters of style rather than of correctness, especially at this point in the life of the book. 😅