I'm sorry for taking so long on this, but this is by far the most daunting chapter I've reviewed so far. I've been daunted enough to think that maybe it's a sign that this chapter has too moving parts, and think it needs at least some reorganization and probably some splitting out into smaller (still dense) chapters. If you can stand to break it into more digestible chunks, I'd suggest something like:
Nested Scope
Global Scope and its Discontents
Variable Visibility (Starts with "When can I use a variable?")
Block Scope (already a separate chapter)
Each of those seems like a field learners can master and know that they've mastered, pause, and move forward.
Intro
This is where readers need to really get down to code, over and over. I'd suggest re-writing the intro to make sure readers know that things are changing, and to welcome them to a much more intense exploration. The intro largely talks about the previous chapter. I'd refocus that on "You've seen X, but now it's time for Y." Gird them for the challenges ahead, and rev them up for it.
I really like the Tip and "This is one of those chapters that really hammers home just how much we all don't know about scope."
Nested Scopes, Revisited
This is mostly fine, but the colors reference when the colors were in the previous chapter and not here is tricky. Since the reference continues into the chapter, maybe re-include the figure?
"Lookup" Is (Mostly) Conceptual
I think a lot of this section depends on the jump from "the information as we have it in this one JS file" to "the information when interpreted in the full context of multiple running JS files."
While I like leaving the marbles "uncolored" as a metaphor, I also want something more. What process will the marble sorting machine use to assign those colors? It's kind of like a pachinko machine, the gates of which are the other JS files coming in. (Maybe this all moves to the Global Scope section? That has the explanation I want.)
I'd integrate the Note pointing to Chapter 2's Lookup Failures into the text as the outcome of that process not working. Also, I'd make that explicitly "Chapter 2's Lookup Failures section". I went looking for a different Chapter 2.
Shadowing
This is a much more comfortable and concrete section. The only thing I'd suggest is starting out by acknowledging the somewhat mysterious headline rather than introducing the word shadowing a page later.
Global Unshadowing Trick
I'd move the Warning information to the first paragraph - make clear to readers that this is something that they should know, but avoid using. I suspect it will entice readers to focus more closely on forbidden knowledge, and will definitely make sure that they don't miss the warning.
I would also take a second look at the paragraph starting with "Notice the window.studentName reference?" You haven't really talked about window or its being effectively global scope in this context, so I'd start with something less puzzling.
Copying is Not Shadowing
This seems strong, except that it makes me long for languages where variables are immutable.
Illegal Shadowing
All seems happy here.
Function Name Scope
Your explanations are solid, but this is one of those corners where I really want a "why is it different?" Is it just history, or are there reasons these differences in behavior are a good idea?
Arrow Functions
I'm really happy to see this story told here - not just the how, but the complications of the "simpler" syntax. At the very least, this gives readers the context they need to figure out where something went weird.
Why Global Scope?
Even if you don't break this chapter into smaller chapters, I'd combine this section with the following "Where Exactly is this Global Scope?" section and its many subsections. The overall topic is Global Scope, and the Why and the Where are parts of that conversation.
The details of the Why section seem to leap into the Where rather than the Why. That seems like another reason to combine it with the Where, but I'd love a few paragraphs on why having global scope at all is a good (or dangerous) idea. It's certainly a contested space....
The information on the effective context of modules and bundled code is excellent. Granted, I want to retreat to my minimal-shared-context-functional-programming world at the end of it, but that's my default.
Where Exactly is This Global Scope?
I'd strongly recommend combining this and its many subsections with the "Why Global Scope?" section to create a single Global Scope section (or preferably chapter).
Browser Window
All happy.
Shadowing Revisited
I think I'd retitle this "Shadowing Global Variables", mostly so people can find it quickly. I'd also lead with the warning rather than conclude with it.
What's in a Name?
The headline is fun, but it took me a moment to figure out what it referred to. Maybe "What's in a window.name?"
Are there more corner cases like this one? If so, a list of the corners would be great, though a full exploration is likely too much.
Web Workers
I think I'd put this section earlier in the list, because it's a simpler (and increasingly more important) exception. Web Workers don't share the main global scope. This is a good thing, because... but they also have their own effective global scope.
Developer Tools Console/REPL
My only concern here is whether the details of this vary from console to console and REPL. I don't think it needs in-depth exploration, but are these things consistent across environments?
ES Modules
I'm not quite sure what this means:
They are not added to any global scope object, nor are they added to any accessible "module-global" object.
Is that "accessible from outside of the module"? They seem accessible from the inside. Is this just normal-ish module encapsulation, or is something more exciting happening?
Node
The Warning ("Node treats every single .js file that it loads...") is the most exciting and probably important part of the section. I think you were aiming to maining continuity with the prior ES modules conversation, but this shift in scope handling is more important. Note it, and then return to the modules conversation.
GlobalThis
Wow. Cross-environment convenience, I guess, but it makes me shudder. Your coverage is fine.
When Can I Use a Variable?
I would open the variable hoisting discussion by noting that historically, it's been a feature that developers stumbled on when their code broke for what seemed like mysterious reasons. Surprise! Once you know about hoisting, debugging is much easier, as is structuring code to avoid (or use) it. (Function hoisting seems much less surprising, I guess because of OOP style in multiple languages.) Maybe frame this whole section and its sub-sections as a series of surprises?
Yet Another Metaphor
I'm wondering if it makes sense to emphasize that "hoisting" is a broken metaphor from the outset and then explain the brokenness, rather than walking through common explanations and wandering into it. Emphasize that people need to know the term "hoisting" to be able to communicate with other developers, but not get caught up in this metaphor.
Re-declaration
Yet more surprises! I'm happy for the clarification on let/var re-declaration errors at the end.
Constants?
This all looks good. I hope you'll return to the "error thrown when re-assigning to studentName is a Type Error, not a Syntax Error" in the Types book.
Loops
Is the scope inside the loop a case of block scope (next chapter?). It seems to me like it should be, and yet...
The explanation for const with the traditional for loop and its rewriting makes me very happy.
Uninitialized
Could you put Temporal Dead Zone into the section header somehow? The name itself seems like to draw readers, and its presence would give a hint at the beginning of what's to come later in the section.
"Many have claimed that" feels weak and oddly political. I don't think you need to say that. Instead something more direct like "TDZ can make it look like let and const do not hoist, but this is inaccurate." Make it less about the debate and more about the code.
Scope Closed
I love the headline, but wish the chapter was broken into smaller ones.
Editorial review, not a searchable issue.
Edition: (1st or 2nd) 2nd
Book Title: Scope & Closures
Chapter: 3
General
I'm sorry for taking so long on this, but this is by far the most daunting chapter I've reviewed so far. I've been daunted enough to think that maybe it's a sign that this chapter has too moving parts, and think it needs at least some reorganization and probably some splitting out into smaller (still dense) chapters. If you can stand to break it into more digestible chunks, I'd suggest something like:
Each of those seems like a field learners can master and know that they've mastered, pause, and move forward.
Intro
This is where readers need to really get down to code, over and over. I'd suggest re-writing the intro to make sure readers know that things are changing, and to welcome them to a much more intense exploration. The intro largely talks about the previous chapter. I'd refocus that on "You've seen X, but now it's time for Y." Gird them for the challenges ahead, and rev them up for it.
I really like the Tip and "This is one of those chapters that really hammers home just how much we all don't know about scope."
Nested Scopes, Revisited
This is mostly fine, but the colors reference when the colors were in the previous chapter and not here is tricky. Since the reference continues into the chapter, maybe re-include the figure?
"Lookup" Is (Mostly) Conceptual
I think a lot of this section depends on the jump from "the information as we have it in this one JS file" to "the information when interpreted in the full context of multiple running JS files."
While I like leaving the marbles "uncolored" as a metaphor, I also want something more. What process will the marble sorting machine use to assign those colors? It's kind of like a pachinko machine, the gates of which are the other JS files coming in. (Maybe this all moves to the Global Scope section? That has the explanation I want.)
I'd integrate the Note pointing to Chapter 2's Lookup Failures into the text as the outcome of that process not working. Also, I'd make that explicitly "Chapter 2's Lookup Failures section". I went looking for a different Chapter 2.
Shadowing
This is a much more comfortable and concrete section. The only thing I'd suggest is starting out by acknowledging the somewhat mysterious headline rather than introducing the word shadowing a page later.
Global Unshadowing Trick
I'd move the Warning information to the first paragraph - make clear to readers that this is something that they should know, but avoid using. I suspect it will entice readers to focus more closely on forbidden knowledge, and will definitely make sure that they don't miss the warning.
I would also take a second look at the paragraph starting with "Notice the window.studentName reference?" You haven't really talked about window or its being effectively global scope in this context, so I'd start with something less puzzling.
Copying is Not Shadowing
This seems strong, except that it makes me long for languages where variables are immutable.
Illegal Shadowing
All seems happy here.
Function Name Scope
Your explanations are solid, but this is one of those corners where I really want a "why is it different?" Is it just history, or are there reasons these differences in behavior are a good idea?
Arrow Functions
I'm really happy to see this story told here - not just the how, but the complications of the "simpler" syntax. At the very least, this gives readers the context they need to figure out where something went weird.
Why Global Scope?
Even if you don't break this chapter into smaller chapters, I'd combine this section with the following "Where Exactly is this Global Scope?" section and its many subsections. The overall topic is Global Scope, and the Why and the Where are parts of that conversation.
The details of the Why section seem to leap into the Where rather than the Why. That seems like another reason to combine it with the Where, but I'd love a few paragraphs on why having global scope at all is a good (or dangerous) idea. It's certainly a contested space....
The information on the effective context of modules and bundled code is excellent. Granted, I want to retreat to my minimal-shared-context-functional-programming world at the end of it, but that's my default.
Where Exactly is This Global Scope?
I'd strongly recommend combining this and its many subsections with the "Why Global Scope?" section to create a single Global Scope section (or preferably chapter).
Browser Window
All happy.
Shadowing Revisited
I think I'd retitle this "Shadowing Global Variables", mostly so people can find it quickly. I'd also lead with the warning rather than conclude with it.
What's in a Name?
The headline is fun, but it took me a moment to figure out what it referred to. Maybe "What's in a window.name?"
Are there more corner cases like this one? If so, a list of the corners would be great, though a full exploration is likely too much.
Web Workers
I think I'd put this section earlier in the list, because it's a simpler (and increasingly more important) exception. Web Workers don't share the main global scope. This is a good thing, because... but they also have their own effective global scope.
Developer Tools Console/REPL
My only concern here is whether the details of this vary from console to console and REPL. I don't think it needs in-depth exploration, but are these things consistent across environments?
ES Modules
I'm not quite sure what this means:
Is that "accessible from outside of the module"? They seem accessible from the inside. Is this just normal-ish module encapsulation, or is something more exciting happening?
Node
The Warning ("Node treats every single .js file that it loads...") is the most exciting and probably important part of the section. I think you were aiming to maining continuity with the prior ES modules conversation, but this shift in scope handling is more important. Note it, and then return to the modules conversation.
GlobalThis
Wow. Cross-environment convenience, I guess, but it makes me shudder. Your coverage is fine.
When Can I Use a Variable?
I would open the variable hoisting discussion by noting that historically, it's been a feature that developers stumbled on when their code broke for what seemed like mysterious reasons. Surprise! Once you know about hoisting, debugging is much easier, as is structuring code to avoid (or use) it. (Function hoisting seems much less surprising, I guess because of OOP style in multiple languages.) Maybe frame this whole section and its sub-sections as a series of surprises?
Yet Another Metaphor
I'm wondering if it makes sense to emphasize that "hoisting" is a broken metaphor from the outset and then explain the brokenness, rather than walking through common explanations and wandering into it. Emphasize that people need to know the term "hoisting" to be able to communicate with other developers, but not get caught up in this metaphor.
Re-declaration
Yet more surprises! I'm happy for the clarification on let/var re-declaration errors at the end.
Constants?
This all looks good. I hope you'll return to the "error thrown when re-assigning to
studentNameis a Type Error, not a Syntax Error" in the Types book.Loops
Is the scope inside the loop a case of block scope (next chapter?). It seems to me like it should be, and yet...
The explanation for const with the traditional for loop and its rewriting makes me very happy.
Uninitialized
Could you put Temporal Dead Zone into the section header somehow? The name itself seems like to draw readers, and its presence would give a hint at the beginning of what's to come later in the section.
"Many have claimed that" feels weak and oddly political. I don't think you need to say that. Instead something more direct like "TDZ can make it look like
letandconstdo not hoist, but this is inaccurate." Make it less about the debate and more about the code.Scope Closed
I love the headline, but wish the chapter was broken into smaller ones.