text updates mostly in 4, plus new images for double loop tdd etc

Author: hjwp

bibliography.asciidoc

@@ -4,6 +4,10 @@
 Bibliography
 ------------
 
+TODO remove this chapter entirely,
+or remove links from text (they dont work),
+and strip down to just the most important books.
+
 - [[[dip]]] Mark Pilgrim, 'Dive Into Python': http://www.diveintopython.net/ 
 - [[[lpthw]]] Zed A. Shaw, 'Learn Python the Hard Way': http://learnpythonthehardway.org/ 
 - [[[iwp]]] Al Sweigart, 'Invent Your Own Computer Games with Python': http://inventwithpython.com

chapter_02_unittest.asciidoc

@@ -108,11 +108,11 @@ I used to virtuously pepper my code with nice descriptive comments.
 My colleagues said to me:
 ``Harry, we have a word for comments. We call them lies.''
 I was shocked!
-But I learned in school that comments are good practice?
+I learned in school that comments are good practice?
 
 They were exaggerating for effect.
 There is definitely a place for comments that add context and intention.
-But their point was that
+But my colleagues' point was that
 _it's pointless to write a comment that just repeats what you're doing with the code_:
 
 [role="skipme"]
@@ -142,6 +142,9 @@ it makes sure we're always testing from the point of view of the user.
 There is more fun to be had in this area, things like
 'Behaviour-Driven Development' (see <<appendix_bdd>>) and testing DSLs, but
 they're topics for other books.
+
+For more on comments, I recommend John Ousterhoudt's _A Philosohpy of Software Design_,
+which you can get a taste of by reading the https://web.stanford.edu/~ouster/cgi-bin/cs190-spring16/lecture.php?topic=comments[lecture notes from the chapter on comments.]
 *******************************************************************************
 
 You'll notice that, apart from writing the test out as comments,

chapter_philosophy_and_refactoring.asciidoc

@@ -341,13 +341,13 @@ OK
 
 Great! We'll start by taking our HTML string and putting it into its own file.
 Create a directory called 'lists/templates' to keep templates in, and then open
-a file at 'lists/templates/home.html', to which we'll transfer our
-HTML:footnote:[Some people like to use another subfolder named after the app
-(i.e., 'lists/templates/lists') and then refer to the template as
-'lists/home.html'.  This is called "template namespacing". I figured it was
-overcomplicated for this small project, but it may be worth it on larger
-projects.  There's more in the
-https://docs.djangoproject.com/en/1.11/intro/tutorial03/#write-views-that-actually-do-something[Django tutorial].]
+a file at 'lists/templates/home.html', to which we'll transfer our HTML:footnote:[
+Some people like to use another subfolder named after the app
+(i.e., 'lists/templates/lists') and then refer to the template as 'lists/home.html'.
+This is called "template namespacing".
+I figured it was overcomplicated for this small project, but it may be worth it on larger projects.
+There's more in the
+https://docs.djangoproject.com/en/4.2/intro/tutorial03/#write-views-that-actually-do-something[Django tutorial].]
 
 [role="sourcecode"]
 .lists/templates/home.html (ch04l002)
@@ -383,11 +383,11 @@ search folders called 'templates' inside any of your apps' directories.  Then
 it builds an `HttpResponse` for you, based on the content of the template.
 
 
-NOTE: Templates are a very powerful feature of Django's, and their main
-    strength consists of substituting Python variables into HTML text. We're
-    not using this feature yet, but we will in future chapters.  That's
-    why we use `render` and (later) +render_to​_string+ rather
-    than, say, manually reading the file from disk with the built-in `open`.
+NOTE: Templates are a very powerful feature of Django's,
+    and their main strength consists of substituting Python variables into HTML text.
+    We're not using this feature yet, but we will in future chapters.
+    That's why we use `render()` rather than, say,
+    manually reading the file from disk with the built-in `open()`.
 
 
 Let's see if it works:
@@ -547,7 +547,7 @@ used to render the response. Actual template(s) used: home.html
 ----
 
 That's very helpful!  Let's change the assert back to the right thing.  While
-we're at it, we can delete our old assertions.  
+we're at it, we can delete our old assertions.
 
 
 [role="sourcecode"]
@@ -597,8 +597,7 @@ notice how that actually would have left space for me to break things: I could
 have defined the template as containing 'any' arbitrary string, instead of
 the string with the right `<html>` and `<title>` tags.
 
-TIP: When refactoring, work on either the code or the tests, but not both at
-     once.
+TIP: When refactoring, work on either the code or the tests, but not both at once.
 
 There's always a tendency to skip ahead a couple of steps, to make a couple of
 tweaks to the behaviour while you're refactoring, but pretty soon you've got
@@ -613,10 +612,10 @@ image::images/twp2_0402.png["An adventurous cat, trying to refactor its way out
 
 
 NOTE: We'll come across ``Refactoring Cat'' again during this book,
-    as an example of what happens when we get carried away and want to change
-    too many things at once. Think of it as the little cartoon demon
-    counterpart to the Testing Goat, popping up over your other shoulder and
-    giving you bad advice...
+    as an example of what happens when we get carried away
+    and want to change too many things at once.
+    Think of it as the little cartoon demon counterpart to the Testing Goat,
+    popping up over your other shoulder and giving you bad advice...
 
 It's a good idea to do a commit after any refactoring:
 
@@ -769,47 +768,62 @@ we've stopped testing constants, and we're now well placed to start processing
 user input.
 
 
-Recap: The TDD Process
-~~~~~~~~~~~~~~~~~~~~~~
+=== Recap: The TDD Process
 
 
-((("Test-Driven Development (TDD)", "overall process of", id="TDDprocess04")))We've
-now seen all the main aspects of the TDD process, in practice:
+((("Test-Driven Development (TDD)", "concepts", "Red/Green/Refactor")))
+((("Red/Green/Refactor")))
+((("unit-test/code cycle")))
+((("Test-Driven Development (TDD)", "overall process of", id="TDDprocess04")))
+We've now seen all the main aspects of the TDD process, in practice:
 
 * Functional tests
 * Unit tests
 * The unit-test/code cycle
 * Refactoring
 
-It's time for a little recap, and perhaps even some flowcharts.  Forgive me,
-years misspent as a management consultant have ruined me. On the plus side,
-it will feature recursion.
+It's time for a little recap, and perhaps even some flowcharts.
+Forgive me, years misspent as a management consultant have ruined me.
+On the plus side, it will feature recursion.
 
-What is the overall TDD process? See <<simple-TDD-diagram>>.
+What is the overall TDD process? 
 
-We write a test. We run the test and see it fail.  We write some minimal code
-to get it a little further.  We rerun the test and repeat until it passes.
-Then, optionally, we might refactor our code, using our tests to make sure we
-don't break anything.
+Well, one very common way to present it is using the three words
+_Red, Green, Refactor_. See <<red-green-refactor>>..
 
-[[simple-TDD-diagram]]
+[[red-green-refactor]]
+.Red, Green, Refactor
+image::images/red-green-refactor-excalidraw.png["Red, Green and Refactor as three nodes in a circle, with arrows flowing around."]
+
+What if we want to drill down in a bit more detail?  Here's what
+we've been doing, including what I call the _unit test/code cycle_:
+
+We write a test. We run the test and see it fail.
+We write some minimal code to get it a little further.
+We rerun the test and repeat until it passes.
+Then, we look for opportunities to refactor our code,
+using our tests to make sure we don't break anything. See <<simple-tdd-diagram>>.
+
+[[simple-tdd-diagram]]
 .Overall TDD process
-image::images/twp2_0403.png["A flowchart showing tests, coding and refactoring"]
-
-But how does this apply when we have functional tests 'and' unit tests?  Well,
-you can think of the functional test as being a high-level view of the cycle,
-where "writing the code" to get the functional tests to pass actually involves
-using another, smaller TDD cycle which uses unit tests. See
-<<Double-Loop-TDD-diagram>>.
-
-We write a functional test and see it fail.  Then, the process of "writing
-code" to get it to pass is a mini-TDD cycle of its own:  we write one or more
-unit tests, and go into the unit-test/code cycle until the unit tests pass.
-Then, we go back to our FT to check that it gets a little further, and we
-can write a bit more of our application--using more unit tests, and so on.
-
-What about refactoring, in the context of functional tests?  Well, that means
-we use the functional test to check that we've preserved the behaviour of
+image::images/tdd-process-unit-tests-only-excalidraw.png["A flowchart with boxes for tests, coding and refactoring, with yes/no labels showing when we move forwards or backwards"]
+
+But how does this apply when we have functional tests _and_ unit tests?
+Well, you can think of the functional test as being a high-level view of the cycle,
+where "writing the code" to get the functional tests to pass
+actually involves using another, smaller TDD cycle which uses unit tests.
+See <<double-loop-tdd-diagram>>.
+
+We write a functional test and see it fail.
+Then, the process of "writing code" to get it to pass is a mini-TDD cycle of its own:
+we write one or more unit tests, and go into the unit-test/code cycle until the unit tests pass.
+Then, we go back to our FT to check that it gets a little further,
+and we can write a bit more of our application--using more unit tests, and so on.
+
+TODO - a little more nuance here
+
+What about refactoring, in the context of functional tests?
+Well, that means we use the functional test to check that we've preserved the behaviour of
 our application, but we can change or add and remove unit tests, and use
 a unit test cycle to actually change the implementation.
 
@@ -820,13 +834,14 @@ This way of looking at things is sometimes called "Double-Loop TDD". One of my
 eminent tech reviewers, Emily Bache, wrote http://bit.ly/1iXzoLR[a blog post]
 on the topic, which I recommend for a different perspective.
 
-[[Double-Loop-TDD-diagram]]
+[[double-loop-tdd-diagram]]
 .The TDD process with functional and unit tests
-image::images/twp2_0404.png["A flowchart showing functional tests as the overall cycle, and unit tests helping to code"]
+image::images/double-loop-tdd-excalidraw.png["A flowchart showing functional tests as the overall cycle, and unit tests helping to code"]
 
 
 We'll explore all of the different parts of this workflow in more detail
-over the coming chapters.((("", startref="TDDprocess04")))
+over the coming chapters.
+((("", startref="TDDprocess04")))
 
 
 

chapter_post_and_database.asciidoc

@@ -548,7 +548,7 @@ The fastest way to get that to pass is with another quick "cheating" change to t
 ((("Test-Driven Development (TDD)", "concepts", "triangulation")))
 ((("triangulation")))
 What I've been referring to as the unit-test/code cycle is often taught
-using the name _Red, Green, Refactor_:
+as a part of the _Red, Green, Refactor_ loop.
 
 1. Start by writing a unit test which fails (_Red_).
 2. Write the simplest possible code to get it to pass (_Green_),