Comments on Chapter 27

chapter_27_hot_lava.asciidoc

@@ -19,6 +19,8 @@ Let's recap our test structure so far:
   They've enabled us to build the app incrementally, to refactor with confidence,
   and they've supported a fast unit-test/code cycle.
 
+// DAVID: For me it reads weirdly to put functional tests and unit tests in speech marks, at this point of the book.
+
 We've also spent a good bit of time on our infrastructure,
 packaging up our app with Docker for ease of deployment,
 and we've set up a CI pipeline to run our tests automatically on push.
@@ -43,13 +45,13 @@ outline several desiderata (desirable characteristics) for tests:
 | *Deterministic*: if nothing changes, the test result shouldn’t change.
 | *Fast*: tests should run quickly.
 | *Writable*: tests should be cheap to write relative to the cost of the code being tested.
-| *Readable*: tests should be comprehensible for reader, invoking the motivation for writing this particular test.
+| *Readable*: tests should be comprehensible for readers, invoking the motivation for writing this particular test.
 | *Behavioural*: tests should be sensitive to changes in the behaviour of the code under test. If the behaviour changes, the test result should change.
 | *Structure-agnostic*: tests should not change their result if the structure of the code changes.
 | *Automated*: tests should run without human intervention.
 | *Specific*: if a test fails, the cause of the failure should be obvious.
 | *Predictive*: if the tests all pass, then the code under test should be suitable for production.
-| *Inspiring*: passing the tests should inspire confidence
+| *Inspiring*: passing the tests should inspire confidence.
 |===
 
 We've talked about almost all of these desiderata in the book:
@@ -143,13 +145,19 @@ and your database "should" be outside of that.
 Why do they say that?
 Apart from the smug from should-ing us?
 
+// DAVID I don't understand that last sentence, is there a typo?
+
 As you can tell,
 I think the argument from _definitions_ is a bit of a red herring.
 But you might hear instead, "the database is hot lava!"
 as Casey Kinsey put it in a memorable DjangoCon talk.
 There is real feeling and real experience behind these comments.
 What are people getting at?
 
+// DAVID: "I think the argument from _definitions_ is a bit of a red herring." - I found this sentence difficult
+// to understand.
+// DAVID: Is it worth a sentence at this point explaining the hot lava connotations? Not
+// having seen the talk, I don't exactly get the analogy -- is hot lava dangerous? Fast? Unpredictable?
 
 ==== Integration and Functional Tests Get Slower Over Time
 
@@ -171,6 +179,9 @@ and associated expenditure on CI.
 We're now spending a lot of effort on trying to move more of our unit
 tests to being "true" unit tests.
 
+// DAVID: More like 12 minutes now!
+// DAVID: Will people know which Kraken you're talking about? Worth a footnote?
+
 The problem is that these things don't scale linearly.
 The more database tables you have,
 the more relationships between them,
@@ -208,6 +219,7 @@ if you spend your time waiting for a slow test suite to run.
 Anything longer than a few seconds and you're going to let your attention wander,
 you context-switch, and the flow state is gone.
 And the flow state is a fragile dream.
+// DAVID: saying it's a dream implies it's not possible. Maybe just 'And the flow state is fragile.'?
 Once it's gone, it takes a long time to come back.footnote:[
 Some people says it takes at least 15 minutes to get back into the flow state.
 In my experience, that's overblown,
@@ -247,6 +259,8 @@ that will still sound like a bit of a mystery.
 So, how can we get to a position where our tests are giving us maximum feedback
 on our design?
 
+// DAVID: It might be worth engaging with the counterargument in the Test Driven Development section in John Ousterhout's
+// A Philosophy of Software Design, in which he argues that TDD impairs design?
 
 
 === The Ideal of the Test Pyramid
@@ -422,6 +436,9 @@ call this approach "Ports and Adapters" (see <<ports-and-adapters>>).
 .Ports and Adapters (diagram by Nat Pryce)
 image::images/twp2_2601.png["Illustration of ports and adapaters architecture, with isolated core and integration points"]
 
+// DAVID: I don't think this diagram is self-explanatory. Nice to break text up with a picture, but
+// maybe this particular one doesn't add much.
+
 This pattern, or variations on it, are known as
 "Hexagonal Architecture" (by Alistair Cockburn),
 "Clean Architecture" (by Robert C. Martin, aka Uncle Bob),
@@ -569,6 +586,8 @@ Inverting the Pyramid::
     for what to do with a project like ours would end up,
     with too many slow tests and not enough fast ones.
 
+// DAVID: Grammar seems off here.
+
 Integration tests are a scam::
     J.B. Rainsberger has a
     http://blog.thecodewhisperer.com/2010/10/16/integrated-tests-are-a-scam/[famous rant]
@@ -583,6 +602,8 @@ Integration tests are a scam::
     analysis of how slow tests kill productivity].
     ((("integrated tests", "benefits and drawbacks of")))
 
+// DAVID: That footnote isn't rendering correctly.
+
 Ports and Adapters::
     Steve Freeman and Nat Pryce wrote about this in <<GOOSGBT, their book>>.
     You can also catch a good discussion in