Merge pull request #273 from ritaf-ORM/patch-9

Rita's edits ch 16

Author: hjwp

chapter_16_javascript.asciidoc

@@ -1,7 +1,7 @@
 [[chapter_16_javascript]]
 == A Gentle Excursion Into JavaScript
 
-[quote, Geoffrey Willans]
+[quote, Geoffrey Willans, English author and journalist]
 ______________________________________________________________
 You can never understand one language until you understand at least two.
 ______________________________________________________________
@@ -24,13 +24,16 @@ once the user started fixing the problem?
 Just like our nice HTML5 validation errors do?
 For that we'd need a teeny-tiny bit of JavaScript.
 
+
+// RITA: In this paragraph, please tell us how we're going to play around with JavaScript and what it'll teach us. I mean, you're going to use Javascript to make it so the duplicate item error message disappears once the user fixes the problem.
 Python is a delightful language to program in.
 JavaScript wasn't always that.
 But many of the rough edges have been smoothed off,
-and I think it's fair to say that it's actually quite nice now.
-And in the world of web development, it's unavoidable.
+and I think it's fair to say that JavaScript is actually quite nice now.
+And in the world of web development, using JavaScript is unavoidable.
 So let's dip our toes in, and see if we can't have a bit of fun.
 
+// RITA: Consider dropping mention of JavaScript: The Good Parts and just referencing your more recent recommendations. If you've read Eloquent JavaScript, consider dropping "I've heard good things" to make your recommendation sound more confident. I suppose you could still mention JavaScript: The Good Parts after that.
 NOTE: I'm going to assume you know the basics of JavaScript syntax.
   If not, I used to recommend https://amzn.to/3UXVUKd[JavaScript: The Good Parts],
   which was the best guide, once upon a time.
@@ -46,6 +49,8 @@ NOTE: I'm going to assume you know the basics of JavaScript syntax.
 
 ((("JavaScript testing", "functional test")))
 ((("functional tests (FTs)", "JavaScript", id="FTjava16")))
+
+// RITA: In this first paragraph, please tell us WHY we're adding a new FT. How does this relate to making it so the duplicate item error messages disappear once the user fixes the problem? Give us context.
 Let's add a new functional test to the `ItemValidationTest` class:
 
 [role="sourcecode"]
@@ -91,7 +96,7 @@ def test_error_messages_are_cleared_on_input(self):
     rather than removing them from the DOM altogether.
 
 
-That fails appropriately:
+The functional test fails appropriately:
 
 
 
@@ -111,6 +116,7 @@ _validation.ItemValidationTest.test_error_messages_are_cleared_on_input)
 AssertionError: True is not false
 ----
 
+// RITA: Move on to do what?
 But, before we move on:  three strikes and refactor!
 We've got several places where we find the error element using CSS.
 Let's move the logic to a helper function:
@@ -199,6 +205,7 @@ TIP: Always do a commit before embarking on a spike.
 
 ==== A Simple Inline Script
 
+// RITA: First thing you came up with to do what?
 I hacked around for a bit,
 and here's more or less the first thing I came up with.
 I'm adding the code inline, in a `<script>` tag
@@ -269,13 +276,13 @@ TIP: It's good practice to put your script loads at the end of your body HTML,
 The test might be happy, but our solution is a little unsatisfactory.
 If you actually try it in your browser,
 you'll see that although the error message is gone,
-the input is still red an invalid-looking, see <<input-still-red>>.
+the input is still red and invalid-looking, see <<input-still-red>>.
 
 [[input-still-red]]
 .The error message is gone but the input box is still red
 image::images/error-gone-but-input-still-red.png["Screenshot of our page where the error div is gone but the input is still red."]
 
-You're probably imagining that this is something to do with Bootstrap.
+You're probably imagining that this has something to do with Bootstrap.
 We might have been able to hide the error message,
 but we also need to tell bootstrap that this input no longer has invalid contents.
 
@@ -298,12 +305,14 @@ but also the red border around the input box.
 We have a reasonable solution now, time to de-spike!
 
 
-.Do we Really Need to Write Unit Tests for This?
+.Do We Really Need to Write Unit Tests for This?
 *******************************************************************************
 
+// RITA: The first sentence following a heading should not refer syntactically to the heading; words should be repeated where necessary.
 By this point in the book, you probably know I'm going to say "yes",
 but let's talk about it anyway.
 
+// RITA: What functionality?
 Our FT definitely covers this functionality,
 and we could extend it if we wanted to,
 to check on the colour of the input box,
@@ -361,7 +370,7 @@ without needing to dive into the whole Node/NPM ecosystem.
 // TODO: go all in and use jasmine-browser-runner instead,
 // it will let me use ES6 modules.
 
-Let's download that now:
+Let's download Jasmine now:
 
 [role="small-code"]
 [subs="specialcharacters,quotes"]
@@ -499,6 +508,8 @@ image::images/jasmine-in-browser-red.png["Jasmine browser-based spec runner show
 
 .Is the Jasmine Standalone Browser Test Runner Unconventional?
 *******************************************************************************
+
+// RITA: Again, the first sentence following a heading should not refer syntactically to the heading; words should be repeated where necessary.
 I think it probably is, to be honest.
 Although the JavaScript world moves so fast,
 I could be wrong by the time you read this.
@@ -637,7 +648,7 @@ on-failure messages into individual `expect/toBe` expressions.
 
 If you refresh the browser, you should see that all passes:
 
-
+// RITA: You don't usually have captions other than commits. Was this one intentional?
 [[first-jasmine-output]]
 .Expected results from Jasmine in the browser
 ====
@@ -653,7 +664,7 @@ Superlists tests
 ----
 ====
 
-
+// RITA: Should this be put into a note box?
 (I'll show the Jasmine outputs as text, as in <<first-jasmine-output>>, from now on,
 to avoid filling the chapter with screenshots.)
 
@@ -769,6 +780,8 @@ Expected true to be false.
 ((("global state")))
 ((("JavaScript testing", "key challenges of", id="JSTkey16")))
 ((("HTML fixtures")))
+
+// RITA: In this paragraph, please tell us how this relates to the goal of the example in this chapter. How does this help the goal of this chapter, which is to get rid of the duplicate item error messages as they are resolved?
 One of the difficulties with JavaScript in general, and testing in particular,
 is in understanding the order of execution of our code (i.e., what happens when).
 When does our code in _lists.js_ run, and when does each of our tests run?  And
@@ -901,7 +914,7 @@ And in our tests file, we call `initialize()` in our key test:
 });
 ----
 ====
-
+//RITA: What does "here" refer to?
 <1> Here.  We don't need to call it in our sense-check.
 
 
@@ -918,7 +931,7 @@ Superlists tests
   * error message should be hidden on input
   * sense-check our html fixture
 ----
-
+// RITA: Why does it make more sense now?
 And now the `console.log` outputs should make more sense:
 
 [role="skipme"]
@@ -934,9 +947,10 @@ initialize called   lists.js:3:11
 === Deliberately Breaking Our Code to Force Ourselves To Write More Tests
 
 I'm always nervous when I see green tests.
-We've copy-pasted 5 lines of code from our spike with just one test?
+We've copy-pasted five lines of code from our spike with just one test.
 That was a little too easy, even despite that little `initialize()` dance.
 
+// RITA: Why do we want to try to deliberately break the initialize function? Give us context.
 Let's change our `initialize()` function to deliberately break it.
 What if we just immediately hide errors?
 
@@ -1041,6 +1055,7 @@ so that they're defined in the same file that actually has the HTML elements.
 
 And while we're at it, our tests could do with a bit of refactoring too!
 
+// RITA: Please tell us the goal of the following code block.
 
 [role="sourcecode"]
 .src/lists/static/tests/Spec.js (ch16l022)
@@ -1256,7 +1271,7 @@ Expected true to be false.
 <Jasmine>
 ----
 
-Ok, back to the right way around:
+OK, back to the right way around:
 
 [role="sourcecode"]
 .src/lists/static/lists.js (ch16l027)
@@ -1334,6 +1349,7 @@ NOTE: We're using `<script>` tag to import our code,
 As the tests flashed past, you may have noticed an unsatisfactory bit of red,
 still left around our input box.
 
+// RITA: Please make sure to conclude this in the spike section so that you can call back to it here.
 Wait a minute!  We forgot one of the key things we learned in our spike!
 We don't need to manually hack `style.display=none`,
 we can work _with_ the Boostrap framework,
@@ -1484,7 +1500,7 @@ And the base template, yay.  Nothing more satisfying than _deleting code_:
 ----
 ====
 
-
+// RITA: Are we missing code here?
 And we can run the FT one more time, just for safety:
 
 
@@ -1497,13 +1513,13 @@ And we can run the FT one more time, just for safety:
 
 [[columbo-onload]]
 === Columbo Says: wait for Onload
-
-[quote, Columbo]
+// RITA: We need a descriptor to give Columbo context. 
+[quote, Columbo, fictional American detective]
 ______________________________________________________________
 Wait, there's just one more thing...
 ______________________________________________________________
 
-
+// RITA: It might be nice to add something to the effect of "before we continue, it's good to do one more thing" so that it ties in with the Columbo quote.
 Finally, whenever you have some JavaScript that interacts with the DOM,
 it's always good to wrap it in some "onload" boilerplate
 to make sure that the page has fully loaded before it tries to do anything.
@@ -1525,7 +1541,7 @@ The modern js onload boilerplate is minimal
     </script>
 ----
 ====
-
+// RITA: Please embed URLs to descriptive text. Also, this link didn't work for me. Please check.
 Read more here
 
 https://developer.mozilla.org/en-US/docs/Web/API/Window/load_even://developer.mozilla.org/en-US/docs/Web/API/Window/load_event
@@ -1540,13 +1556,14 @@ https://developer.mozilla.org/en-US/docs/Web/API/Window/load_even://developer.mo
 You may be wondering how these JavaScript tests fit in with our "double loop" TDD cycle.
 The answer is that they play exactly the same role as our Python unit tests.
 
+// RITA: Please add a sentence to introduce this list. What is the process described by the items in the list?
 1. Write an FT and see it fail.
 2. Figure out what kind of code you need next: Python or JavaScript?
 3. Write a unit test in either language, and see it fail.
 4. Write some code in either language, and make the test pass.
 5. Rinse and repeat.
 
-
+// RITA: Tell the reader what will happen in Part 3. Also, tell us the next step will be covered in the next chapter.
 We're almost ready to move on to <<part3>>.  The last step is to deploy our
 new code to our servers.
 Don't forget to do a final commit including _base.html_ first!
@@ -1588,7 +1605,7 @@ NOTE: Want a little more practice with JavaScript?  See if you can get our
 ((("global state")))
 
 * An awful lot of frontend work these days is done in frameworks,
-  React being the 1000-pound gorilla.
+  React being the 1,000-pound gorilla.
   There are lots of resources on React testing out there,
   so I'll let you go out and find them if you need them.